[ { "path": ".circleci/README.md", "content": "## CircleCI integration\n\n### Docker images\n\nThe docker images are built locally on the developer machine:\n\n```sh\ncd .circleci/docker/\n\ndocker build -t ethereum/solidity-buildpack-deps:ubuntu2404- -f Dockerfile.ubuntu2404 .\ndocker push ethereum/solidity-buildpack-deps:ubuntu2404-\n```\n\nThe 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 `-docker-image-rev` (e.g., `ubuntu-2404-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 (`` 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.\n\nOnce the docker image has been built and pushed to Docker Hub, you can find it at:\n\n https://hub.docker.com/r/ethereum/solidity-buildpack-deps:ubuntu2404-\n\nwhere the image tag reflects the target OS and revision to build Solidity and run its tests on.\n\n### Testing docker images locally\n\n```sh\ncd solidity\n# Mounts your local solidity directory in docker container for testing\ndocker run -v `pwd`:/src/solidity -ti ethereum/solidity-buildpack-deps:ubuntu2404- /bin/bash\ncd /src/solidity\n\n```\n" }, { "path": ".circleci/cln-asan.supp", "content": "leak:*libcln*\n" }, { "path": ".circleci/compare_bytecode_reports.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n#------------------------------------------------------------------------------\n# Compares bytecode reports generated by prepare_report.py/.js.\n#\n# ------------------------------------------------------------------------------\n# This file is part of solidity.\n#\n# solidity is free software: you can redistribute it and/or modify\n# it under the terms of the GNU General Public License as published by\n# the Free Software Foundation, either version 3 of the License, or\n# (at your option) any later version.\n#\n# solidity is distributed in the hope that it will be useful,\n# but WITHOUT ANY WARRANTY; without even the implied warranty of\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n# GNU General Public License for more details.\n#\n# You should have received a copy of the GNU General Public License\n# along with solidity. If not, see \n#\n# (c) 2023 solidity contributors.\n#------------------------------------------------------------------------------\n\nno_cli_platforms=(\n emscripten\n)\nnative_platforms=(\n ubuntu2004-static\n ubuntu_arm\n ubuntu\n osx\n osx_intel\n windows\n)\ninterfaces=(\n cli\n standard-json\n)\n\nfor preset in \"$@\"; do\n report_files=()\n for platform in \"${no_cli_platforms[@]}\"; do\n report_files+=(\"bytecode-report-${platform}-${preset}.txt\")\n done\n for platform in \"${native_platforms[@]}\"; do\n for interface in \"${interfaces[@]}\"; do\n report_files+=(\"bytecode-report-${platform}-${interface}-${preset}.txt\")\n done\n done\n\n echo \"Reports to compare:\"\n printf -- \"- %s\\n\" \"${report_files[@]}\"\n\n if ! diff --brief --report-identical-files --from-file \"${report_files[@]}\"; then\n diff --unified=0 --report-identical-files --from-file \"${report_files[@]}\" | head --lines 50\n zip \"bytecode-reports-${preset}.zip\" \"${report_files[@]}\"\n exit 1\n fi\ndone\n" }, { "path": ".circleci/config.yml", "content": "# vim:ts=2:sw=2:et\n# --------------------------------------------------------------------------\n# Prefixes used in order to keep CircleCI workflow overview more readable:\n# - b: build\n# - t: test\n# - ubu: ubuntu\n# - ems: Emscripten\nversion: 2.1\nparameters:\n ubuntu-2004-docker-image:\n type: string\n # ghcr.io/argotorg/solidity-buildpack-deps:ubuntu2004-26\n default: \"ghcr.io/argotorg/solidity-buildpack-deps@sha256:1f387a77be889f65a2a25986a5c5eccc88cec23fabe6aeaf351790751145c81e\"\n ubuntu-2404-docker-image:\n type: string\n # ghcr.io/argotorg/solidity-buildpack-deps:ubuntu2404-7\n default: \"ghcr.io/argotorg/solidity-buildpack-deps@sha256:e52bd8fbb38908f203c6866e39562548faf26e5b7a5174f9860b44aae2b8f0cd\"\n ubuntu-2404-arm-docker-image:\n type: string\n # ghcr.io/argotorg/solidity-buildpack-deps:ubuntu2404.arm-3\n default: \"ghcr.io/argotorg/solidity-buildpack-deps@sha256:1e6dbf9a9173f2645449281a1e11918a95ca6dc04e59aa9d70824cffc44697ed\"\n ubuntu-2404-clang-docker-image:\n type: string\n # ghcr.io/argotorg/solidity-buildpack-deps:ubuntu2404.clang-8\n default: \"ghcr.io/argotorg/solidity-buildpack-deps@sha256:e283c8ec6a59c76565c89b856d8019af2fa5beb96f27d3064fc4dda42bf3524d\"\n ubuntu-clang-ossfuzz-docker-image:\n type: string\n # ghcr.io/argotorg/solidity-buildpack-deps:ubuntu.clang.ossfuzz-13\n default: \"ghcr.io/argotorg/solidity-buildpack-deps@sha256:2acb5d6f254ece25a96096f26960b5fe114eb86ceca92312cd20d59c096bf6e4\"\n emscripten-docker-image:\n type: string\n # NOTE: Please remember to update the `scripts/build_emscripten.sh` whenever the hash of this image changes.\n # ghcr.io/argotorg/solidity-buildpack-deps:emscripten-22\n default: \"ghcr.io/argotorg/solidity-buildpack-deps@sha256:b9c953144d82cca5553f65626bc43b8af456dbc8966f8732ff9522f33ca8d722\"\n evm-version:\n type: string\n default: osaka\n\norbs:\n win: circleci/windows@2.2.0\n\ncommands:\n matrix_notify_unless_pr:\n description: \"Posts a notification to the solidity-dev room on Matrix (if not running on a PR).\"\n parameters:\n event:\n type: enum\n enum: [\"failure\", \"success\", \"release\"]\n condition:\n type: string\n steps:\n - run:\n name: \"Matrix notification\"\n when: << parameters.condition >>\n command: scripts/ci/notification/matrix_notification.sh << parameters.event >>\n\n matrix_notify_failure_unless_pr:\n description: \"Posts a failure notification to the main room on Matrix (if not running on a PR).\"\n steps:\n - matrix_notify_unless_pr:\n event: failure\n condition: on_fail\n\n matrix_notify_success_unless_pr:\n description: \"Posts a success notification to the main room on Matrix (if not running on a PR).\"\n steps:\n - matrix_notify_unless_pr:\n event: success\n condition: on_success\n\n matrix_notify_release_unless_pr:\n description: \"Posts a release notification to the main room on Matrix (if not running on a PR).\"\n steps:\n - matrix_notify_unless_pr:\n event: release\n condition: on_success\n\n restore_ccache_if_allowed:\n description: \"Restore ccache unless on a tag or a skipped branch.\"\n parameters:\n skip_branches_regex:\n description: \"Regex of branches that should skip restoring the cache.\"\n type: string\n default: \"^(develop|breaking)$\"\n steps:\n # Tags always skip ccache. Selected branches intentionally start from scratch.\n - when:\n condition:\n and:\n - equal: [\"\", << pipeline.git.tag >>]\n - not:\n matches:\n pattern: \"<< parameters.skip_branches_regex >>\"\n value: << pipeline.git.branch >>\n steps:\n - restore_cache:\n keys:\n # Reuse cache produced on develop (prefix match; restores the most recent).\n - v1-ccache-{{ .Environment.CIRCLE_JOB }}-develop-\n\n save_ccache_if_develop:\n description: \"Save a fresh ccache only on the develop branch.\"\n steps:\n # On `develop` we always generate a fresh cache by never restoring and by saving under a unique key.\n - when:\n condition:\n equal: [\"develop\", << pipeline.git.branch >>]\n steps:\n - save_cache:\n key: v1-ccache-{{ .Environment.CIRCLE_JOB }}-develop-{{ .Revision }}\n paths:\n - ~/.ccache\n run_with_ccache_unless_tag:\n description: \"Run a command with ccache enabled unless building a tag.\"\n parameters:\n command:\n type: string\n step_name:\n type: string\n steps:\n - when:\n condition:\n equal: [\"\", << pipeline.git.tag >>]\n steps:\n - run:\n name: << parameters.step_name >> (ccache)\n command: << parameters.command >>\n - when:\n condition:\n not:\n equal: [\"\", << pipeline.git.tag >>]\n steps:\n - run:\n name: << parameters.step_name >> (no ccache)\n command: CCACHE_DISABLE=1 << parameters.command >>\n\n prepare_bytecode_report:\n description: \"Generate bytecode report and upload it as an artifact.\"\n parameters:\n label:\n type: string\n binary_type:\n type: enum\n enum:\n - solcjs\n - native\n - osx_intel\n binary_path:\n type: string\n preset:\n type: string\n steps:\n - run:\n name: Generate bytecode reports for the selected preset\n command: |\n .circleci/parallel_bytecode_report.sh \\\n \"<< parameters.label >>\" \\\n \"<< parameters.binary_type >>\" \\\n \"${PWD}/<< parameters.binary_path >>\" \\\n \"<< parameters.preset >>\"\n - store_artifacts:\n path: bytecode-report-<< parameters.label >>-standard-json-<< parameters.preset >>.txt\n - store_artifacts:\n path: bytecode-report-<< parameters.label >>-cli-<< parameters.preset >>.txt\n - store_artifacts:\n path: bytecode-report-<< parameters.label >>-<< parameters.preset >>.txt\n - persist_to_workspace:\n root: .\n paths:\n - bytecode-report-<< parameters.label >>*.txt\n - matrix_notify_failure_unless_pr\n\n install_python3:\n description: \"Install python3 and given packages.\"\n parameters:\n packages:\n description: \"List of extra Python packages to be installed (separated by space).\"\n type: string\n default: \"\"\n steps:\n - run:\n name: Install python and dependencies\n command: |\n sudo apt update\n sudo apt install python3 python3-pip --assume-yes --no-install-recommends\n if [[ \"<< parameters.packages >>\" != \"\" ]]\n then\n echo \"Installing additional packages...\"\n python3 -m pip install --user --break-system-packages << parameters.packages >>\n fi\n\n install_foundry:\n description: \"Install Foundry.\"\n parameters:\n version:\n type: string\n default: \"stable\"\n install_path:\n type: string\n default: /home/circleci/bin\n steps:\n - run:\n name: Setup Foundry environment variables\n command: |\n FOUNDRY_REPO=\"foundry-rs/foundry\"\n FOUNDRY_VERSION=\"<< parameters.version >>\"\n RELEASE_URL=\"https://github.com/${FOUNDRY_REPO}/releases/download/${FOUNDRY_VERSION}\"\n echo \"export FOUNDRY_VERSION=${FOUNDRY_VERSION}\" >> \"$BASH_ENV\"\n echo \"export RELEASE_URL=${RELEASE_URL}\" >> \"$BASH_ENV\"\n ATTESTATION_URL=$(curl --silent --location --fail \"${RELEASE_URL}/foundry_${FOUNDRY_VERSION}_linux_amd64.attestation.txt\") || {\n echo \"Failed to fetch attestation file\"\n exit 1\n }\n ATTESTATION_JSON=$(curl --silent --location --fail --header \"Accept: application/json\" \"${ATTESTATION_URL}\") || {\n echo \"Failed to fetch attestation JSON\"\n exit 1\n }\n RELEASE_SHA=$(echo \"${ATTESTATION_JSON}\" | jq --raw-output '.payload.attestation.sourceRepositoryDigest')\n if [[ -z \"$RELEASE_SHA\" || \"$RELEASE_SHA\" == \"null\" ]]; then\n echo \"Failed to extract release SHA from attestation\"\n exit 1\n fi\n echo \"${RELEASE_SHA}\" > /tmp/workspace/foundry-release-sha\n # Extract forge checksum from the attestation\n EXPECTED_FORGE_CHECKSUM=$(echo \"${ATTESTATION_JSON}\" | jq --raw-output '.payload.attestation.subjects[] | select(.subjectName==\"forge\") | .subjectDigest' | sed 's/sha256://')\n if [[ -z \"$EXPECTED_FORGE_CHECKSUM\" || \"$EXPECTED_FORGE_CHECKSUM\" == \"null\" ]]; then\n echo \"Failed to extract forge checksum from attestation\"\n exit 1\n fi\n echo \"export EXPECTED_FORGE_CHECKSUM=${EXPECTED_FORGE_CHECKSUM}\" >> \"$BASH_ENV\"\n - restore_cache:\n keys:\n - foundry-v1-<< parameters.version >>-{{ arch }}-{{ checksum \"/tmp/workspace/foundry-release-sha\" }}\n # WARNING! If you edit anything between here and save_cache, remember to invalidate the cache manually.\n - run:\n name: Install foundry\n command: |\n if forge --version 2> /dev/null; then\n echo \"Foundry already cached, skipping install\"\n else\n curl --fail --location --output /tmp/foundry.tar.gz \"${RELEASE_URL}/foundry_${FOUNDRY_VERSION}_linux_amd64.tar.gz\"\n cd \"<< parameters.install_path >>\"\n tar --extract --gzip --file /tmp/foundry.tar.gz --one-top-level\n # TODO: Use `gh attestation verify foundry/forge --owner foundry-rs` for signature verification.\n # Current approach only verifies checksum without validating the signature.\n # https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations#verifying-an-artifact-attestation-for-binaries\n ACTUAL=$(sha256sum foundry/forge | cut --delimiter=' ' --fields=1)\n if [[ \"$EXPECTED_FORGE_CHECKSUM\" != \"$ACTUAL\" ]]; then\n echo \"Checksum mismatch: expected $EXPECTED_FORGE_CHECKSUM, got $ACTUAL\"\n exit 1\n fi\n ln --symbolic --force foundry/{forge,anvil,cast,chisel} .\n fi\n - save_cache:\n key: foundry-v1-<< parameters.version >>-{{ arch }}-{{ checksum \"/tmp/workspace/foundry-release-sha\" }}\n paths:\n - << parameters.install_path >>\n\n # --------------------------------------------------------------------------\n # Build Commands\n\n setup_prerelease:\n steps:\n - run:\n name: Store prerelease suffix\n command: |\n \"scripts/prerelease_suffix.sh\" nightly \"$CIRCLE_TAG\" > prerelease.txt\n\n install_and_check_minimum_requirements:\n parameters:\n compiler:\n description: \"Compiler to check: gcc or clang\"\n type: enum\n enum:\n - gcc\n - clang\n steps:\n - run:\n name: Install and check minimum requirements\n command: scripts/ci/install_and_check_minimum_requirements.sh \"--<< parameters.compiler >>\"\n\n run_build:\n steps:\n - restore_ccache_if_allowed\n # WARNING! If you edit anything between here and save_cache, remember to invalidate the cache manually by bumping the version\n - run_with_ccache_unless_tag:\n step_name: Build\n command: scripts/ci/build.sh\n - save_ccache_if_develop\n\n run_build_ossfuzz:\n steps:\n - restore_ccache_if_allowed\n # WARNING! If you edit anything between here and save_cache, remember to invalidate the cache manually by bumping the version\n - run_with_ccache_unless_tag:\n step_name: Build_ossfuzz\n command: scripts/ci/build_ossfuzz.sh\n - save_ccache_if_develop\n\n run_proofs:\n steps:\n - run:\n name: Correctness proofs for optimization rules\n command: scripts/run_proofs.sh\n\n run_soltest:\n steps:\n - run:\n name: soltest\n no_output_timeout: 30m\n command: .circleci/soltest.sh\n\n run_soltest_all:\n parameters:\n # NOTE: If not specified, soltest_all.sh will use the default values as specified in the script.\n # In other words, it will execute for all EVM versions that are not marked as low priority.\n evm_versions:\n description: \"List of EVM versions (separated by space).\"\n type: string\n default: \"\"\n steps:\n - run:\n name: soltest_all\n no_output_timeout: 30m\n command: .circleci/soltest_all.sh \"<< parameters.evm_versions >>\"\n\n run_cmdline_tests:\n steps:\n - run:\n name: command line tests\n no_output_timeout: 30m\n command: .circleci/parallel_cli_tests.py\n\n run_docs_pragma_min_version:\n steps:\n - run:\n name: docs pragma version check\n command: scripts/docs_version_pragma_check.sh\n\n # --------------------------------------------------------------------------\n # Artifact Commands\n\n store_artifacts_solc:\n description: Store compiled solc executable as artifact\n steps:\n - store_artifacts:\n path: build/solc/solc\n destination: solc\n\n store_artifacts_yul_phaser:\n steps:\n - store_artifacts:\n path: build/tools/yul-phaser\n destination: yul-phaser\n\n persist_executables_to_workspace:\n description: Persist compiled target executables to workspace\n steps:\n - persist_to_workspace:\n root: build\n paths:\n - solc/solc\n - test/soltest\n - test/tools/solfuzzer\n\n persist_executables_to_workspace_arm:\n description: Persist compiled target executables to workspace on Linux arm64\n steps:\n - persist_to_workspace:\n root: build\n paths:\n - solc/solc-static-linux-arm\n - test/soltest-linux-arm\n - test/tools/solfuzzer-linux-arm\n\n persist_executables_to_workspace_osx:\n description: Persist compiled target executables to workspace on macOS\n steps:\n - persist_to_workspace:\n root: .\n paths:\n - build/solc/solc\n - build/test/soltest\n - build/test/tools/solfuzzer\n\n persist_ossfuzz_executables_to_workspace:\n description: Persist compiled OSSFUZZ executables to workspace\n steps:\n - persist_to_workspace:\n root: build\n paths:\n - test/tools/ossfuzz/abiv2_proto_ossfuzz\n - test/tools/ossfuzz/abiv2_isabelle_ossfuzz\n - test/tools/ossfuzz/const_opt_ossfuzz\n - test/tools/ossfuzz/solc_mutator_ossfuzz\n - test/tools/ossfuzz/solc_ossfuzz\n - test/tools/ossfuzz/stack_reuse_codegen_ossfuzz\n - test/tools/ossfuzz/strictasm_assembly_ossfuzz\n - test/tools/ossfuzz/strictasm_diff_ossfuzz\n - test/tools/ossfuzz/strictasm_opt_ossfuzz\n - test/tools/ossfuzz/yul_proto_diff_ossfuzz\n - test/tools/ossfuzz/yul_proto_diff_custom_mutate_ossfuzz\n - test/tools/ossfuzz/yul_proto_ossfuzz\n - test/tools/ossfuzz/sol_proto_ossfuzz\n\n store_artifacts_test_results:\n description: Store test output dir as artifact\n steps:\n - store_artifacts:\n path: test_results/\n destination: test_results/\n\n # --------------------------------------------------------------------------\n # Complex Build Commands\n\n soltest:\n steps:\n - checkout\n - attach_workspace:\n at: build\n # NOTE: Different build jobs produce different soltest executables (release/debug,\n # clang/gcc, windows/linux/macos, etc.). The executable used by these steps comes from the\n # attached workspace and we only see the items added to the workspace by jobs we depend on.\n - run_soltest\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n test_lsp:\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run:\n name: Executing solc LSP test suite\n command: test/lsp.py build/solc/solc --non-interactive\n - matrix_notify_failure_unless_pr\n\n build:\n steps:\n - checkout\n - run_build\n - store_artifacts_solc\n - store_artifacts_yul_phaser\n - persist_executables_to_workspace\n - matrix_notify_failure_unless_pr\n\n soltest_all:\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run_soltest_all\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n cmdline_tests:\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run_cmdline_tests\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n install_dependencies_osx:\n # An extra cache key is used to only save the flag that communicates whether the cache exists.\n # if this flag was set (the cache exist) we remove all files located in /usr/local & /opt/homebrew.\n # With this simple trick restoring the cache is much faster. Otherwise CircleCI is generating\n # warning messages if a file from the cache is overwriting an already existing file on disk.\n # Restoring the cache is much faster if we remove all potentially conflicting files beforehand.\n steps:\n - restore_cache:\n keys:\n - macos-dependencies-cached-{{ arch }}-{{ checksum \".circleci/osx_install_dependencies.sh\" }}\n - run:\n name: Installing dependencies / Restoring dependency cache\n command: |\n if [[ -f ~/macos-dependencies-cached ]]; then\n echo \"Dependency flag exists. Removing /usr/local/, /opt/homebrew/, and /opt/boost. These directories will be restored from cache.\"\n\n # CircleCI is providing the circleci cli tools via some kind of symlink magic.\n # So we just save the original symlinks and restore them later.\n circleci_binary_path=$(command -v circleci)\n circleci_agent_binary_path=$(command -v circleci-agent)\n cp \"${circleci_binary_path}\" /tmp/circleci\n cp \"${circleci_agent_binary_path}\" /tmp/circleci-agent\n\n # Homebrew is installed in /usr/local on intel macs, but in /opt/homebrew on apple silicon.\n if [[ -d /opt/homebrew ]]; then\n sudo rm -rf /opt/homebrew\n sudo mkdir -p /opt/homebrew/bin\n sudo chmod 777 /opt/{homebrew,homebrew/bin}\n fi\n # under macos /usr/local itself is read-only, so we just remove its sub-directories.\n sudo rm -rf /usr/local/*\n sudo mkdir -p /usr/local/bin\n sudo chmod 777 /usr/{local,local/bin}\n\n sudo rm -rf /opt/boost\n sudo mkdir -p /opt/boost\n sudo chmod 777 /opt/boost\n\n mv /tmp/circleci \"${circleci_binary_path}\"\n mv /tmp/circleci-agent \"${circleci_agent_binary_path}\"\n fi\n - restore_cache:\n keys:\n - macos-dependencies-{{ arch }}-{{ checksum \".circleci/osx_install_dependencies.sh\" }}\n # DO NOT EDIT between here and save_cache, but rather edit ./circleci/osx_install_dependencies.sh\n # WARNING! If you do edit anything here instead, remember to invalidate the cache manually.\n - run:\n name: Install build dependencies\n command: .circleci/osx_install_dependencies.sh\n - run:\n name: Mark dependencies as cached\n command: touch ~/macos-dependencies-cached\n - save_cache:\n key: macos-dependencies-{{ arch }}-{{ checksum \".circleci/osx_install_dependencies.sh\" }}\n paths:\n # Homebrew is installed in /usr/local on intel macs, but in /opt/homebrew on apple silicon.\n - /usr/local\n - /opt/homebrew\n - /opt/boost\n - save_cache:\n key: macos-dependencies-cached-{{ arch }}-{{ checksum \".circleci/osx_install_dependencies.sh\" }}\n paths:\n - ~/macos-dependencies-cached\n\ndefaults:\n\n # --------------------------------------------------------------------------\n # Matrix templates\n\n - bytecode_compare_env_presets: &bytecode_compare_env_presets\n PRESETS:\n legacy-optimize\n legacy-no-optimize\n via-ir-optimize\n via-ir-no-optimize\n\n - bytecode_compare_preset_matrix: &bytecode_compare_preset_matrix\n parameters:\n preset:\n # NOTE: Keep in sync with preset list in bytecode_compare_env_presets\n - legacy-optimize\n - legacy-no-optimize\n - via-ir-optimize\n - via-ir-no-optimize\n\n # --------------------------------------------------------------------------\n # --------------------------------------------------------------------------\n # Base Image Templates\n\n - base_archlinux: &base_archlinux\n docker:\n - image: archlinux:base\n environment: &base_archlinux_env\n TERM: xterm\n MAKEFLAGS: -j 3\n CPUs: 3\n\n - base_archlinux_large: &base_archlinux_large\n <<: *base_archlinux\n resource_class: large\n environment: &base_archlinux_large_env\n <<: *base_archlinux_env\n MAKEFLAGS: -j 5\n CPUs: 5\n\n - base_cimg_small: &base_cimg_small\n docker:\n - image: cimg/base:current\n resource_class: small\n environment: &base_cimg_small_env\n TERM: xterm\n MAKEFLAGS: -j 2\n CPUs: 2\n\n - base_ems_large: &base_ems_large\n docker:\n - image: << pipeline.parameters.emscripten-docker-image >>\n resource_class: large\n environment: &base_ems_large_env\n TERM: xterm\n MAKEFLAGS: -j 5\n CPUs: 5\n\n - base_node_small: &base_node_small\n docker:\n - image: cimg/node:current\n resource_class: small\n environment: &base_node_small_env\n TERM: xterm\n MAKEFLAGS: -j 2\n CPUs: 2\n\n - base_osx: &base_osx\n macos:\n xcode: 15.4.0\n resource_class: m4pro.medium\n environment: &base_osx_env\n TERM: xterm\n MAKEFLAGS: -j8\n CPUs: 8\n\n - base_ubuntu_clang: &base_ubuntu_clang\n docker:\n - image: << pipeline.parameters.ubuntu-clang-ossfuzz-docker-image >>\n environment: &base_ubuntu_clang_env\n TERM: xterm\n MAKEFLAGS: -j 3\n CPUs: 3\n\n - base_ubuntu_clang_small: &base_ubuntu_clang_small\n <<: *base_ubuntu_clang\n resource_class: small\n environment: &base_ubuntu_clang_small_env\n <<: *base_ubuntu_clang_env\n MAKEFLAGS: -j 2\n CPUs: 2\n\n - base_ubuntu_clang_large: &base_ubuntu_clang_large\n <<: *base_ubuntu_clang\n resource_class: large\n environment: &base_ubuntu_clang_small_env\n <<: *base_ubuntu_clang_env\n MAKEFLAGS: -j 5\n CPUs: 5\n\n - base_ubuntu2004: &base_ubuntu2004\n docker:\n - image: << pipeline.parameters.ubuntu-2004-docker-image >>\n environment: &base_ubuntu2004_env\n TERM: xterm\n MAKEFLAGS: -j 3\n CPUs: 3\n\n - base_ubuntu2004_small: &base_ubuntu2004_small\n <<: *base_ubuntu2004\n resource_class: small\n environment: &base_ubuntu2004_small_env\n <<: *base_ubuntu2004_env\n MAKEFLAGS: -j 2\n CPUs: 2\n\n - base_ubuntu2004_xlarge: &base_ubuntu2004_xlarge\n <<: *base_ubuntu2004\n resource_class: xlarge\n environment: &base_ubuntu2004_xlarge_env\n <<: *base_ubuntu2004_env\n MAKEFLAGS: -j 10\n CPUs: 10\n\n - base_ubuntu2404: &base_ubuntu2404\n docker:\n - image: << pipeline.parameters.ubuntu-2404-docker-image >>\n environment: &base_ubuntu2404_env\n TERM: xterm\n MAKEFLAGS: -j 3\n CPUs: 3\n\n - base_ubuntu2404_clang: &base_ubuntu2404_clang\n docker:\n - image: << pipeline.parameters.ubuntu-2404-clang-docker-image >>\n environment: &base_ubuntu2404_clang_env\n TERM: xterm\n CC: clang\n CXX: clang++\n MAKEFLAGS: -j 3\n CPUs: 3\n\n - base_ubuntu2404_clang_large: &base_ubuntu2404_clang_large\n <<: *base_ubuntu2404_clang\n resource_class: large\n environment: &base_ubuntu2404_clang_large_env\n <<: *base_ubuntu2404_clang_env\n MAKEFLAGS: -j 5\n CPUs: 5\n\n - base_ubuntu2404_small: &base_ubuntu2404_small\n <<: *base_ubuntu2404\n resource_class: small\n environment: &base_ubuntu2404_small_env\n <<: *base_ubuntu2404_env\n MAKEFLAGS: -j 2\n CPUs: 2\n\n - base_ubuntu2404_large: &base_ubuntu2404_large\n <<: *base_ubuntu2404\n resource_class: large\n environment: &base_ubuntu2404_large_env\n <<: *base_ubuntu2404_env\n MAKEFLAGS: -j 5\n CPUs: 5\n\n - base_ubuntu2404_arm_medium: &base_ubuntu2404_arm_medium\n docker:\n - image: << pipeline.parameters.ubuntu-2404-arm-docker-image >>\n resource_class: arm.medium\n environment: &base_ubuntu2404_arm_medium_env\n TERM: xterm\n MAKEFLAGS: -j 2\n CPUs: 2\n\n - base_ubuntu2404_arm_large: &base_ubuntu2404_arm_large\n docker:\n - image: << pipeline.parameters.ubuntu-2404-arm-docker-image >>\n resource_class: arm.large\n environment: &base_ubuntu2404_arm_large_env\n TERM: xterm\n MAKEFLAGS: -j 7\n CPUs: 7\n\n - base_ubuntu2404_xlarge: &base_ubuntu2404_xlarge\n <<: *base_ubuntu2404\n resource_class: xlarge\n environment: &base_ubuntu2404_xlarge_env\n <<: *base_ubuntu2404_env\n MAKEFLAGS: -j 10\n CPUs: 10\n\n - base_win: &base_win\n executor:\n name: win/default\n shell: bash.exe\n\n - base_win_large: &base_win_large\n executor:\n name: win/default\n size: large\n shell: bash.exe\n\n # --------------------------------------------------------------------------\n # Workflow Templates\n\n - on_all_tags_and_branches: &on_all_tags_and_branches\n filters:\n tags:\n only: /.*/\n\n - on_version_tags: &on_version_tags\n filters:\n tags:\n only: /^v.*/\n branches:\n ignore: /.*/\n\n - on_develop: &on_develop\n filters:\n branches:\n only:\n - develop\n\n - requires_nothing: &requires_nothing\n <<: *on_all_tags_and_branches\n\n - requires_b_ubu: &requires_b_ubu\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu\n\n - requires_b_ubu_clang: &requires_b_ubu_clang\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_clang\n\n - requires_b_ubu_force_release: &requires_b_ubu_force_release\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_force_release\n\n - requires_b_ubu_static: &requires_b_ubu_static\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_static\n\n - requires_b_ubu_static_arm: &requires_b_ubu_static_arm\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_static_arm\n\n - requires_b_archlinux: &requires_b_archlinux\n <<: *on_all_tags_and_branches\n requires:\n - b_archlinux\n\n - requires_b_osx: &requires_b_osx\n <<: *on_all_tags_and_branches\n requires:\n - b_osx\n\n - requires_b_ubu_asan: &requires_b_ubu_asan\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_asan\n\n - requires_b_ubu_asan_clang: &requires_b_ubu_asan_clang\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_asan_clang\n\n - requires_b_ubu_ubsan_clang: &requires_b_ubu_ubsan_clang\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_ubsan_clang\n\n - requires_b_ems: &requires_b_ems\n <<: *on_all_tags_and_branches\n requires:\n - b_ems\n\n - requires_b_ubu_ossfuzz: &requires_b_ubu_ossfuzz\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_ossfuzz\n\n - requires_b_win: &requires_b_win\n <<: *on_all_tags_and_branches\n requires:\n - b_win\n\n # --------------------------------------------------------------------------\n # Parameterized Job Templates\n\n # Separate compile-only runs of those external tests where a full run takes much longer.\n # Also see https://github.com/argotorg/solidity/pull/14234 for why we excluded those\n # external tests from the nightly jobs.\n - job_ems_compile_ext_colony: &job_ems_compile_ext_colony\n <<: *requires_b_ems\n name: t_ems_compile_ext_colony\n project: colony\n binary_type: solcjs\n compile_only: 1\n image: cimg/node:14.20\n python2: true\n\n - job_native_compile_ext_gnosis: &job_native_compile_ext_gnosis\n <<: *requires_b_ubu_static\n name: t_native_compile_ext_gnosis\n project: gnosis\n binary_type: native\n # NOTE: We are disabling the gnosis test suite due to version discrepancies that are difficult to fix.\n # Check again after (and if) https://github.com/safe-global/safe-contracts/pull/644 is merged.\n compile_only: 1\n image: cimg/node:18.16\n\n - job_native_test_ext_zeppelin: &job_native_test_ext_zeppelin\n <<: *requires_b_ubu_static\n name: t_native_test_ext_zeppelin\n project: zeppelin\n binary_type: native\n image: cimg/node:lts\n resource_class: large\n\n - job_native_test_ext_ens: &job_native_test_ext_ens\n <<: *requires_b_ubu_static\n name: t_native_test_ext_ens\n project: ens\n binary_type: native\n image: cimg/node:lts\n\n - job_native_compile_ext_trident: &job_native_compile_ext_trident\n <<: *requires_b_ubu_static\n name: t_native_compile_ext_trident\n project: trident\n binary_type: native\n # NOTE: test suite disabled due to dependence on a specific version of Hardhat\n # which does not support shanghai EVM.\n compile_only: 1\n image: cimg/node:18.16\n\n - job_native_compile_ext_euler: &job_native_compile_ext_euler\n <<: *requires_b_ubu_static\n name: t_native_compile_ext_euler\n project: euler\n binary_type: native\n resource_class: medium\n\n - job_native_test_ext_yield_liquidator: &job_native_test_ext_yield_liquidator\n <<: *requires_b_ubu_static\n name: t_native_test_ext_yield_liquidator\n project: yield-liquidator\n binary_type: native\n image: cimg/node:18.16\n\n - job_native_compile_ext_bleeps: &job_native_compile_ext_bleeps\n <<: *requires_b_ubu_static\n name: t_native_compile_ext_bleeps\n project: bleeps\n binary_type: native\n # NOTE: test suite disabled due to dependence on a specific version of Hardhat\n # which does not support shanghai EVM.\n compile_only: 1\n resource_class: medium\n\n - job_native_compile_ext_pool_together: &job_native_compile_ext_pool_together\n <<: *requires_b_ubu_static\n name: t_native_compile_ext_pool_together\n project: pool-together\n binary_type: native\n # NOTE: test suite disabled due to dependence on a specific version of Hardhat\n # which does not support shanghai EVM.\n compile_only: 1\n image: cimg/node:lts\n\n - job_native_test_ext_uniswap: &job_native_test_ext_uniswap\n <<: *requires_b_ubu_static\n name: t_native_test_ext_uniswap\n project: uniswap\n binary_type: native\n image: cimg/node:lts\n resource_class: large # Tests run out of memory on a smaller machine\n\n - job_native_test_ext_prb_math: &job_native_test_ext_prb_math\n <<: *requires_b_ubu_static\n name: t_native_test_ext_prb_math\n project: prb-math\n binary_type: native\n image: cimg/rust:1.74.0-node\n resource_class: large # Tests run out of memory on a smaller machine\n\n - job_native_test_ext_elementfi: &job_native_test_ext_elementfi\n <<: *requires_b_ubu_static\n name: t_native_test_ext_elementfi\n project: elementfi\n binary_type: native\n image: cimg/node:lts\n resource_class: medium\n\n - job_native_test_ext_brink: &job_native_test_ext_brink\n <<: *requires_b_ubu_static\n name: t_native_test_ext_brink\n project: brink\n binary_type: native\n image: cimg/node:lts\n\n - job_native_compile_ext_chainlink: &job_native_compile_ext_chainlink\n <<: *requires_b_ubu_static\n name: t_native_compile_ext_chainlink\n project: chainlink\n binary_type: native\n # NOTE: test suite disabled due to dependence on a specific version of Hardhat\n # which does not support shanghai EVM.\n compile_only: 1\n image: cimg/node:16.20\n resource_class: large # Tests run out of memory on a smaller machine\n\n - job_native_compile_ext_gp2: &job_native_compile_ext_gp2\n <<: *requires_b_ubu_static\n name: t_native_compile_ext_gp2\n project: gp2\n binary_type: native\n # NOTE: test suite disabled due to constant failures.\n compile_only: 1\n image: cimg/node:lts\n\n - job_b_ubu_asan_clang: &job_b_ubu_asan_clang\n <<: *on_all_tags_and_branches\n name: b_ubu_asan_clang\n cmake_options: -DSANITIZE=address\n\n - job_b_ubu_ubsan_clang: &job_b_ubu_ubsan_clang\n <<: *on_all_tags_and_branches\n name: b_ubu_ubsan_clang\n cmake_options: -DSANITIZE=undefined\n\n# -----------------------------------------------------------------------------------------------\njobs:\n\n chk_spelling:\n <<: *base_ubuntu2404_small\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run:\n name: Install dependencies\n command: |\n pip install --user codespell\n - run:\n name: Check spelling\n command: ~/.local/bin/codespell\n - matrix_notify_failure_unless_pr\n\n chk_docs_examples:\n <<: *base_node_small\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run:\n name: JS deps\n command: sudo npm install -g solhint\n - run:\n name: Test Docs examples\n command: test/docsCodeStyle.sh\n - matrix_notify_failure_unless_pr\n\n chk_coding_style:\n <<: *base_cimg_small\n steps:\n - checkout\n - run:\n name: Install shellcheck\n command: |\n sudo apt -q update\n sudo apt install -y shellcheck\n - run:\n name: Check for C++ coding style\n command: scripts/check_style.sh\n - run:\n name: checking shell scripts\n command: scripts/chk_shellscripts/chk_shellscripts.sh\n - run:\n name: Check for broken symlinks\n command: scripts/check_symlinks.sh\n - matrix_notify_failure_unless_pr\n\n chk_errorcodes:\n <<: *base_ubuntu2404_small\n steps:\n - checkout\n - run:\n name: Check for error codes\n command: scripts/error_codes.py --check\n - matrix_notify_failure_unless_pr\n\n chk_pylint:\n <<: *base_ubuntu2404_small\n steps:\n - install_python3:\n packages: pyyaml jsonschema pytest\n - checkout\n - run: pylint --version\n - run:\n name: Linting Python Scripts\n command: scripts/pylint_all.py\n - matrix_notify_failure_unless_pr\n\n chk_antlr_grammar:\n <<: *base_cimg_small\n steps:\n - checkout\n - run:\n name: Install Java\n command: |\n sudo apt -q update\n sudo apt install -y openjdk-17-jdk\n - run:\n name: Run tests\n command: scripts/test_antlr_grammar.sh\n - matrix_notify_failure_unless_pr\n\n chk_buglist:\n <<: *base_node_small\n steps:\n - checkout\n - run:\n name: JS deps\n command: |\n npm install download\n npm install JSONPath\n npm install mktemp\n - run:\n name: Test buglist\n command: test/buglistTests.js\n - matrix_notify_failure_unless_pr\n\n chk_proofs:\n <<: *base_ubuntu2404_small\n steps:\n - checkout\n - run_proofs\n - matrix_notify_failure_unless_pr\n\n chk_docs_pragma_min_version:\n <<: *base_ubuntu2404_small\n steps:\n - checkout\n - run_docs_pragma_min_version\n - matrix_notify_failure_unless_pr\n\n t_ubu_pyscripts:\n <<: *base_ubuntu2404_small\n steps:\n - checkout\n - run:\n name: Python unit tests\n command: python3 test/pyscriptTests.py\n - run:\n name: Smoke test for gas_diff_stats.py\n command: scripts/gas_diff_stats.py\n - matrix_notify_failure_unless_pr\n\n t_win_pyscripts:\n <<: *base_win\n steps:\n - run: git config --global core.autocrlf false\n - checkout\n - run:\n name: Install dependencies\n command: python -m pip install --user requests parsec tabulate\n - run:\n name: Python unit tests\n command: python.exe test/pyscriptTests.py\n - matrix_notify_failure_unless_pr\n\n b_ubu: &b_ubu\n # this runs 2x faster on xlarge but takes 4x more resources (compared to medium).\n # Enough other jobs depend on it that it's worth it though.\n <<: *base_ubuntu2404_xlarge\n steps:\n - build\n - run: cat prerelease.txt\n\n # x64 ASAN build, for testing for memory related bugs\n b_ubu_asan: &b_ubu_asan\n # Runs slightly faster on large and xlarge but we only run it nightly so efficiency matters more.\n <<: *base_ubuntu2404\n environment:\n <<: *base_ubuntu2404_env\n # NOTE: Sanitizers may alter the intermediate code, potentially causing false warnings.\n # As a result, treating warnings as errors in instrumented builds can lead to build failures due to these false positives.\n # Therefore, we disable pedantic builds in such cases.\n # See: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=105562#c27\n CMAKE_OPTIONS: -DSANITIZE=address -DPEDANTIC=OFF\n CMAKE_BUILD_TYPE: Release\n # Set the number of jobs to two instead of the default three, so that we do not run out of memory\n MAKEFLAGS: -j 2\n steps:\n - build\n\n b_ubu_clang: &b_ubu_clang\n <<: *base_ubuntu2404_clang_large\n environment:\n <<: *base_ubuntu2404_clang_large_env\n MAKEFLAGS: -j 10\n steps:\n - build\n\n b_ubu_san_clang:\n # This runs a bit faster on large and xlarge but on nightly efficiency matters more.\n parameters:\n cmake_options:\n type: string\n <<: *base_ubuntu2404_clang\n environment:\n <<: *base_ubuntu2404_clang_env\n # NOTE: Disabled pedantic builds to avoid false positives, see b_ubu_asan for a more detailed explanation.\n CMAKE_OPTIONS: -DPEDANTIC=OFF << parameters.cmake_options >>\n steps:\n - build\n\n b_ubu_force_release: &b_ubu_force_release\n <<: *b_ubu\n environment:\n <<: *base_ubuntu2404_xlarge_env\n FORCE_RELEASE: ON\n\n b_ubu_static:\n # We temporarily keep building static release binaries on ubuntu 20.04\n # to avoid glibc incompatibilities.\n # See: https://github.com/argotorg/solidity/issues/13954\n # On large runs 2x faster than on medium. 3x on xlarge.\n <<: *base_ubuntu2404_xlarge\n environment:\n <<: *base_ubuntu2404_xlarge_env\n CMAKE_OPTIONS: -DCMAKE_BUILD_TYPE=Release -DSOLC_LINK_STATIC=ON\n steps:\n - checkout\n - run_build\n - run:\n name: strip binary\n command: strip build/solc/solc\n - store_artifacts:\n path: build/solc/solc\n destination: solc-static-linux\n - run: mv build/solc/solc build/solc/solc-static-linux\n - persist_to_workspace:\n root: build\n paths:\n - solc/solc-static-linux\n - matrix_notify_failure_unless_pr\n\n b_ubu_static_arm: &b_ubu_static_arm\n <<: *base_ubuntu2404_arm_large\n environment:\n <<: *base_ubuntu2404_arm_large_env\n CMAKE_OPTIONS: -DCMAKE_BUILD_TYPE=Release -DSOLC_LINK_STATIC=ON\n steps:\n - checkout\n - run_build\n - run:\n name: strip binary\n command: strip build/solc/solc\n - store_artifacts:\n path: build/solc/solc\n destination: solc-static-linux-arm\n - run: mv build/solc/solc build/solc/solc-static-linux-arm\n - run: mv build/test/soltest build/test/soltest-linux-arm\n - run: mv build/test/tools/solfuzzer build/test/tools/solfuzzer-linux-arm\n - persist_executables_to_workspace_arm\n - matrix_notify_failure_unless_pr\n\n b_ubu_min_req:\n <<: *base_ubuntu2404_large\n steps:\n - checkout\n - install_and_check_minimum_requirements:\n compiler: gcc\n - run_build\n - store_artifacts_solc\n - persist_executables_to_workspace\n - matrix_notify_failure_unless_pr\n - build\n\n b_ubu_min_req_clang:\n <<: *base_ubuntu2404_clang_large\n environment:\n <<: *base_ubuntu2404_clang_large_env\n MAKEFLAGS: -j 10\n steps:\n - checkout\n - install_and_check_minimum_requirements:\n compiler: clang\n - run_build\n - matrix_notify_failure_unless_pr\n\n t_ubu_min_req_soltest:\n <<: *base_ubuntu2404_large\n parallelism: 20\n environment:\n <<: *base_ubuntu2404_large_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n OPTIMIZE: 0\n steps:\n - soltest\n\n b_ubu_ossfuzz: &b_ubu_ossfuzz\n <<: *base_ubuntu_clang_large\n steps:\n - checkout\n - setup_prerelease\n - run_build_ossfuzz\n - persist_ossfuzz_executables_to_workspace\n - matrix_notify_failure_unless_pr\n\n t_ubu_ossfuzz: &t_ubu_ossfuzz\n <<: *base_ubuntu_clang_small\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run:\n name: Regression tests\n command: |\n git clone https://github.com/argotorg/solidity-fuzzing-corpus /tmp/solidity-fuzzing-corpus\n mkdir -p test_results\n scripts/regressions.py -o test_results\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n\n b_archlinux:\n <<: *base_archlinux_large\n environment:\n <<: *base_archlinux_large_env\n steps:\n - run:\n name: Install build dependencies\n command: |\n pacman --noconfirm -Syu --noprogressbar --needed base-devel boost cmake ccache git openssh tar\n - checkout\n - run_build\n - store_artifacts_solc\n - persist_executables_to_workspace\n - matrix_notify_failure_unless_pr\n\n b_osx:\n <<: *base_osx\n environment:\n <<: *base_osx_env\n CMAKE_BUILD_TYPE: Release\n # boost root configured to the prefix used in `osx_install_dependencies.sh`\n CMAKE_OPTIONS: -DCMAKE_OSX_ARCHITECTURES:STRING=x86_64;arm64 -DBoost_ROOT=/opt/boost\n steps:\n - checkout\n - install_dependencies_osx\n - run_build\n - store_artifacts_solc\n - store_artifacts_yul_phaser\n - persist_executables_to_workspace_osx\n - matrix_notify_failure_unless_pr\n\n t_osx_soltest: &t_osx_soltest\n <<: *base_osx\n environment:\n <<: *base_osx_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n OPTIMIZE: 0\n steps:\n - checkout\n - install_dependencies_osx\n - attach_workspace:\n at: .\n - run_soltest\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n t_osx_cli:\n <<: *base_osx\n parallelism: 8 # Should match number of tests in .circleci/parallel_cli_tests.py\n steps:\n - checkout\n - install_dependencies_osx\n - attach_workspace:\n at: .\n - run_cmdline_tests\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n b_ems:\n <<: *base_ems_large\n environment:\n <<: *base_ems_large_env\n MAKEFLAGS: -j 10\n steps:\n - checkout\n - restore_ccache_if_allowed\n # WARNING! If you edit anything between here and save_cache, remember to invalidate the cache manually by bumping the version\n - run_with_ccache_unless_tag:\n step_name: Build\n command: scripts/ci/build_emscripten.sh\n - save_ccache_if_develop\n - store_artifacts:\n path: upload/soljson.js\n destination: soljson.js\n - run: mkdir -p workspace\n - run: cp upload/soljson.js workspace/soljson.js\n - run: scripts/get_version.sh > workspace/version.txt\n - persist_to_workspace:\n root: workspace\n paths:\n - soljson.js\n - version.txt\n - matrix_notify_failure_unless_pr\n\n b_docs:\n <<: *base_ubuntu2404_small\n steps:\n - checkout\n - setup_prerelease\n - run:\n name: Install build system dependencies\n command: |\n apt-get update\n apt-get install --quiet=2 --no-install-recommends python3-dev libcairo2-dev pkg-config\n - run:\n name: Build documentation\n command: docs/docs.sh\n - store_artifacts:\n path: docs/_build/html/\n destination: docs-html\n - matrix_notify_failure_unless_pr\n\n t_ubu_soltest: &t_ubu_soltest\n <<: *base_ubuntu2404_large\n parallelism: 20\n environment:\n <<: *base_ubuntu2404_large_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n OPTIMIZE: 0\n steps:\n - soltest\n\n t_ubu_arm_soltest: &t_ubu_arm_soltest\n <<: *base_ubuntu2404_arm_medium\n parallelism: 20\n environment:\n <<: *base_ubuntu2404_arm_medium_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n OPTIMIZE: 0\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run:\n name: Create symbolic link with expected soltest binary name\n command: |\n ln --symbolic --relative build/test/soltest-linux-arm build/test/soltest\n - run_soltest\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n t_ubu_soltest_low_priority_evm_versions: &t_ubu_soltest_low_priority_evm_versions\n <<: *base_ubuntu2404_large\n parallelism: 50\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run_soltest_all:\n # We test most EVM versions on every PR. The ones below are the exceptions.\n #\n # We do not test these at all. We were never doing that and no point starting now since\n # they are deprecated anyway:\n # - tangerineWhistle\n # - spuriousDragon\n #\n # These have a low chance of breaking so we only run them in nightly to save credits:\n # - byzantium: deprecated, if it breaks, homestead likely will as well\n # - petersburg: no changes compared to constantinople\n # - prague: no changes compared to cancun\n evm_versions: byzantium petersburg prague\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n t_ubu_lsp: &t_ubu_lsp\n <<: *base_ubuntu2404_small\n steps:\n - test_lsp\n\n t_archlinux_soltest: &t_archlinux_soltest\n <<: *base_archlinux\n parallelism: 20\n environment:\n <<: *base_archlinux_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n OPTIMIZE: 0\n # For Archlinux we do not have prebuilt docker images and we would need to build evmone from source,\n # thus we forgo semantics tests to speed things up.\n SOLTEST_FLAGS: --no-semantic-tests --no-smt\n steps:\n - run:\n name: Install runtime dependencies\n command: |\n pacman --noconfirm -Syu --noprogressbar --needed z3 git\n - soltest\n\n t_ubu_clang_soltest: &t_ubu_clang_soltest\n <<: *base_ubuntu2404_clang\n parallelism: 20\n environment:\n <<: *base_ubuntu2404_clang_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n OPTIMIZE: 0\n # The high parallelism in this job is causing the SMT tests to run out of memory,\n # so disabling for now.\n SOLTEST_FLAGS: --no-smt\n steps:\n - soltest\n\n t_ubu_force_release_soltest_all: &t_ubu_force_release_soltest_all\n <<: *base_ubuntu2404_large\n parallelism: 50\n steps:\n - soltest_all\n\n t_ubu_cli: &t_ubu_cli\n <<: *base_ubuntu2404_small\n parallelism: 8 # Should match number of tests in .circleci/parallel_cli_tests.py\n steps:\n - cmdline_tests\n\n t_ubu_arm_cli: &t_ubu_arm_cli\n <<: *base_ubuntu2404_arm_medium\n parallelism: 8 # Should match number of tests in .circleci/parallel_cli_tests.py\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run:\n name: Create symbolic link with expected solc and solfuzzer binaries name\n command: |\n ln --symbolic --relative build/solc/solc-static-linux-arm build/solc/solc\n ln --symbolic --relative build/test/tools/solfuzzer-linux-arm build/test/tools/solfuzzer\n - run_cmdline_tests\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n t_ubu_force_release_cli: &t_ubu_force_release_cli\n <<: *t_ubu_cli\n\n t_ubu_locale:\n <<: *base_ubuntu2404_small\n steps:\n - checkout\n - attach_workspace:\n at: build\n - run: test/localeTest.sh build/solc/solc\n - matrix_notify_failure_unless_pr\n\n t_ubu_asan_cli:\n # Runs slightly faster on medium but we only run it nightly so efficiency matters more.\n <<: *base_ubuntu2404\n parallelism: 8 # Should match number of tests in .circleci/parallel_cli_tests.py\n environment:\n <<: *base_ubuntu2404_env\n ASAN_OPTIONS: check_initialization_order=true:detect_stack_use_after_return=true:strict_init_order=true:strict_string_checks=true:detect_invalid_pointer_pairs=2\n # Suppress CLN memory leak.\n # See: https://github.com/argotorg/solidity/issues/13891 for details.\n LSAN_OPTIONS: suppressions=/root/project/.circleci/cln-asan.supp:print_suppressions=0\n steps:\n - cmdline_tests\n\n t_ubu_asan_soltest:\n <<: *base_ubuntu2404\n parallelism: 20\n environment:\n <<: *base_ubuntu2404_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n OPTIMIZE: 0\n SOLTEST_FLAGS: --no-smt\n ASAN_OPTIONS: check_initialization_order=true:detect_stack_use_after_return=true:strict_init_order=true:strict_string_checks=true:detect_invalid_pointer_pairs=2\n # Suppress CLN memory leak.\n # See: https://github.com/argotorg/solidity/issues/13891 for details.\n LSAN_OPTIONS: suppressions=/root/project/.circleci/cln-asan.supp\n steps:\n - soltest\n\n t_ubu_asan_clang_soltest:\n <<: *base_ubuntu2404_clang\n parallelism: 20\n environment:\n <<: *base_ubuntu2404_clang_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n OPTIMIZE: 0\n SOLTEST_FLAGS: --no-smt\n ASAN_OPTIONS: check_initialization_order=true:detect_stack_use_after_return=true:strict_init_order=true:strict_string_checks=true:detect_invalid_pointer_pairs=2\n steps:\n - soltest\n\n t_ubu_ubsan_clang_soltest:\n <<: *base_ubuntu2404_clang\n parallelism: 20\n environment:\n <<: *base_ubuntu2404_clang_env\n EVM: << pipeline.parameters.evm-version >>\n EOF_VERSION: 0\n SOLTEST_FLAGS: --no-smt\n steps:\n - soltest\n\n t_ubu_ubsan_clang_cli:\n <<: *base_ubuntu2404_clang\n parallelism: 8 # Should match number of tests in .circleci/parallel_cli_tests.py\n steps:\n - cmdline_tests\n\n t_ems_solcjs:\n # Unlike other t_ems jobs this one actually runs 2x faster on medium (compared to small).\n <<: *base_ubuntu2404\n steps:\n - checkout\n - attach_workspace:\n at: /tmp/workspace\n - run:\n name: Install test dependencies\n command: |\n apt-get update\n apt-get install -qqy --no-install-recommends nodejs npm\n - run:\n name: Test solcjs\n no_output_timeout: 30m\n command: |\n node --version\n npm --version\n test/externalTests/solc-js/solc-js.sh /tmp/workspace/soljson.js $(cat /tmp/workspace/version.txt)\n - matrix_notify_failure_unless_pr\n\n t_ems_ext_edr:\n # Runs out of memory on the small instance\n <<: *base_ubuntu2404\n docker:\n - image: cimg/rust:1.79.0-node\n environment:\n <<: *base_ubuntu2404_env\n EDR_TESTS_SOLC_PATH: /tmp/workspace/soljson.js\n steps:\n - checkout\n - attach_workspace:\n at: /tmp/workspace\n - run:\n name: Ensure pnpm is installed if npm is present\n command: sudo npm install -g pnpm\n - run:\n name: Retrieve EDR latest release tag\n command: |\n # Make authenticated requests when the Github token is available\n if [[ -n \"$GITHUB_READ_TOKEN\" ]]; then\n EXTRA_HEADERS=(--header \"Authorization: Bearer ${GITHUB_READ_TOKEN}\")\n fi\n EDR_LATEST_RELEASE_TAG=$(\n curl \\\n --silent \\\n --location \\\n --fail \\\n --show-error \\\n \"${EXTRA_HEADERS[@]}\" \\\n https://api.github.com/repos/nomicfoundation/edr/releases/latest \\\n | jq --raw-output .tag_name \\\n )\n echo \"export EDR_LATEST_RELEASE_TAG='${EDR_LATEST_RELEASE_TAG}'\" >> \"$BASH_ENV\"\n - run: git clone --depth 1 https://github.com/nomicfoundation/edr.git --branch \"$EDR_LATEST_RELEASE_TAG\"\n - run:\n name: Install dependencies\n command: |\n cd edr\n pnpm install --no-frozen-lockfile\n - run:\n name: Run hardhat-tests in EDR repo\n command: |\n EDR_TESTS_SOLC_VERSION=$(scripts/get_version.sh)\n export EDR_TESTS_SOLC_VERSION\n\n cd edr/hardhat-tests\n pnpm test\n - matrix_notify_failure_unless_pr\n\n t_ext:\n parameters:\n project:\n type: string\n binary_type:\n type: enum\n enum:\n - solcjs\n - native\n compile_only:\n type: integer\n default: 0\n image:\n type: string\n default: cimg/node:current\n resource_class:\n type: string\n default: small\n python2:\n type: boolean\n default: false\n docker:\n - image: << parameters.image >>\n resource_class: << parameters.resource_class >>\n # NOTE: Each external test runs up to 6 independent settings presets. If parallelism is higher than\n # actual preset count, some runs will exit immediately. If it's lower, some runs will get more than one preset.\n parallelism: 6\n environment:\n TERM: xterm\n COMPILE_ONLY: << parameters.compile_only >>\n steps:\n - checkout\n - attach_workspace:\n at: /tmp/workspace\n - install_foundry\n - run:\n name: Ensure pnpm is installed if npm is present\n command: |\n if command -v npm &> /dev/null; then\n sudo npm install -g pnpm\n fi\n - when:\n condition: << parameters.python2 >>\n steps:\n - run:\n name: Install Python 2 and make it the default\n command: |\n sudo apt update\n # python is used by node-gyp to build native modules (needed for Colony).\n # In the 14.x image node-gyp still requires Python 2.\n sudo apt install python2 --assume-yes --no-install-recommends\n sudo update-alternatives --install /usr/bin/python python /usr/bin/python2 1\n - when:\n condition:\n equal: [<< parameters.binary_type >>, \"solcjs\"]\n steps:\n - run:\n name: External << parameters.project >> tests (<< parameters.binary_type >>)\n command: |\n test/external_tests.py test --solc-binary-type \"<< parameters.binary_type >>\" --solc-binary-path /tmp/workspace/soljson.js --run \"<< parameters.project >>\"\n - when:\n condition:\n equal: [<< parameters.binary_type >>, \"native\"]\n steps:\n - run:\n name: External << parameters.project >> tests (<< parameters.binary_type >>)\n command: |\n test/external_tests.py test --solc-binary-type \"<< parameters.binary_type >>\" --solc-binary-path /tmp/workspace/solc/solc-static-linux --run \"<< parameters.project >>\"\n - store_artifacts:\n path: reports/externalTests/\n # persist_to_workspace fails if the directory does not exist and the test script will create\n # it only if it actually has benchmark results.\n - run: mkdir -p reports/externalTests/\n - persist_to_workspace:\n root: .\n paths:\n - reports/externalTests/\n - matrix_notify_failure_unless_pr\n\n t_ethdebug_output_validity:\n <<: *base_node_small\n steps:\n - checkout\n - attach_workspace:\n at: /tmp/workspace\n - install_python3:\n packages: pyyaml jsonschema pytest\n - run:\n name: Ethdebug validity tests\n command: |\n pytest test/ethdebugSchemaTests --solc-binary-path=/tmp/workspace/solc/solc-static-linux -v\n\n c_ext_benchmarks:\n <<: *base_node_small\n steps:\n - install_python3:\n packages: requests\n - checkout\n - attach_workspace:\n at: .\n - run:\n name: Combine benchmark reports\n command: cat reports/externalTests/benchmark-*.json | scripts/externalTests/merge_benchmarks.sh > reports/externalTests/all-benchmarks.json\n - run:\n name: Summarize reports\n command: cat reports/externalTests/all-benchmarks.json | scripts/externalTests/summarize_benchmarks.sh > reports/externalTests/summarized-benchmarks.json\n - store_artifacts:\n path: reports/externalTests/all-benchmarks.json\n - store_artifacts:\n path: reports/externalTests/summarized-benchmarks.json\n - run:\n name: Check CircleCI token presence; Skip remaining steps if the token is not present.\n command: |\n # NOTE: download_benchmarks.py requires CIRCLECI_TOKEN environment variable to be set to\n # a valid CircleCI API token to download the benchmark artifacts.\n if [[ -z \"$CIRCLECI_TOKEN\" ]]; then\n echo \"Skipping download benchmarks...\"\n circleci-agent step halt\n fi\n - run:\n name: Download reports from base branch\n command: |\n if [[ $CIRCLE_PULL_REQUEST != \"\" ]]; then\n mkdir reports/externalTests/base-branch/\n cd reports/externalTests/base-branch/\n\n pr_id=$(echo \"$CIRCLE_PULL_REQUEST\" | sed 's|\\(.*\\)\\/||')\n scripts_dir=../../../scripts\n\n # Our main goal here is to provide new benchmarks, the diff is optional. When benchmarks from\n # the previous run are not available for whatever reason, we still succeed and just skip the diff.\n # download_benchmarks.py exits with status 2 in that case.\n if \"${scripts_dir}/externalTests/download_benchmarks.py\" --base-of-pr \"$pr_id\" || [[ $? == 2 ]]; then\n echo 'export SKIP_BENCHMARK_DIFF=true' >> $BASH_ENV\n fi\n fi\n - run:\n name: Diff benchmarks\n command: |\n if [[ $CIRCLE_PULL_REQUEST != \"\" && $SKIP_BENCHMARK_DIFF != \"true\" ]]; then\n cd reports/externalTests/\n mkdir diff/\n scripts_dir=../../scripts\n\n \"${scripts_dir}/externalTests/benchmark_diff.py\" table \\\n --output-format markdown \\\n --style humanized \\\n base-branch/summarized-benchmarks-*.json \\\n summarized-benchmarks.json > diff/benchmark-diff-summarized-table-markdown-humanized.md\n \"${scripts_dir}/externalTests/benchmark_diff.py\" table \\\n --output-format markdown \\\n --style absolute \\\n base-branch/summarized-benchmarks-*.json \\\n summarized-benchmarks.json > diff/benchmark-diff-summarized-table-markdown-absolute.md\n \"${scripts_dir}/externalTests/benchmark_diff.py\" inplace \\\n --style absolute \\\n base-branch/summarized-benchmarks-*.json \\\n summarized-benchmarks.json > diff/benchmark-diff-summarized-inplace-absolute.md\n \"${scripts_dir}/externalTests/benchmark_diff.py\" inplace \\\n --style absolute \\\n base-branch/all-benchmarks-*.json \\\n all-benchmarks.json > diff/benchmark-diff-all-table-inplace-absolute.md\n fi\n - store_artifacts:\n path: reports/externalTests/diff/\n - store_artifacts:\n path: reports/externalTests/base-branch/\n\n b_win: &b_win\n <<: *base_win_large\n steps:\n # NOTE: Not disabling git's core.autocrlf here because we want to build using the typical Windows config.\n - checkout\n - restore_cache:\n keys:\n - dependencies-win-{{ arch }}-{{ checksum \"scripts/install_deps.ps1\" }}\n # DO NOT EDIT between here and save_cache, but rather edit .\\scripts\\install_deps.ps1\n # WARNING! If you do edit anything here instead, remember to invalidate the cache manually.\n - run:\n name: \"Installing dependencies\"\n command: .\\scripts\\install_deps.ps1\n shell: powershell.exe\n - save_cache:\n key: dependencies-win-{{ arch }}-{{ checksum \"scripts/install_deps.ps1\" }}\n paths:\n - .\\deps\n - restore_ccache_if_allowed\n # WARNING! If you edit anything between here and save_cache, remember to invalidate the cache manually by bumping the version\n - run_with_ccache_unless_tag:\n step_name: \"Building solidity\"\n command: scripts/ci/build_win.sh\n - save_ccache_if_develop\n - run:\n name: \"Run solc.exe to make sure build was successful.\"\n command: .\\build\\solc\\Release\\solc.exe --version\n shell: powershell.exe\n - store_artifacts:\n path: upload/\n - persist_to_workspace:\n root: build\n paths:\n - .\\solc\\*\\solc.exe\n - .\\test\\*\\soltest.exe\n - matrix_notify_failure_unless_pr\n\n t_win_soltest: &t_win_soltest\n <<: *base_win\n steps:\n # NOTE: Git's default core.autocrlf is fine for running soltest. We get additional coverage\n # for files using CRLF that way.\n - checkout\n - attach_workspace:\n at: build\n - run:\n name: \"Install evmone\"\n command: scripts/install_evmone.ps1\n shell: powershell.exe\n - run:\n name: \"Run soltest\"\n command: .circleci/soltest.ps1\n shell: powershell.exe\n - run:\n name: Install LSP test dependencies\n command: python -m pip install --user numpy deepdiff colorama\n - run:\n name: Executing solc LSP test suite\n command: python test/lsp.py build\\solc\\Release\\solc.exe --non-interactive\n shell: powershell.exe\n - store_test_results:\n path: test_results/\n - store_artifacts_test_results\n - matrix_notify_failure_unless_pr\n\n # Note: b_bytecode_ubu_static is required because b_ubu_static and b_ubu\n # are currently built on different Ubuntu base images.\n # It can be safely removed once we move both to the same Ubuntu version.\n b_bytecode_ubu_static:\n parameters:\n preset:\n type: string\n <<: *base_ubuntu2004_small\n parallelism: 2 # For prepare_bytecode_report\n steps:\n - checkout\n - attach_workspace:\n at: build\n - prepare_bytecode_report:\n label: \"ubuntu2004-static\"\n binary_type: native\n binary_path: \"build/solc/solc-static-linux\"\n preset: \"<< parameters.preset >>\"\n\n b_bytecode_ubu:\n parameters:\n preset:\n type: string\n <<: *base_ubuntu2404_small\n parallelism: 2 # For prepare_bytecode_report\n steps:\n - checkout\n - attach_workspace:\n at: build\n - prepare_bytecode_report:\n label: \"ubuntu\"\n binary_type: native\n binary_path: \"build/solc/solc\"\n preset: \"<< parameters.preset >>\"\n\n b_bytecode_osx:\n parameters:\n preset:\n type: string\n <<: *base_osx\n parallelism: 2 # For prepare_bytecode_report\n steps:\n - checkout\n - attach_workspace:\n at: .\n - prepare_bytecode_report:\n label: \"osx\"\n binary_type: native\n binary_path: \"build/solc/solc\"\n preset: \"<< parameters.preset >>\"\n\n b_bytecode_osx_intel:\n parameters:\n preset:\n type: string\n <<: *base_osx\n parallelism: 2 # For prepare_bytecode_report\n steps:\n - checkout\n - attach_workspace:\n at: .\n - prepare_bytecode_report:\n label: \"osx_intel\"\n binary_type: osx_intel\n binary_path: \"build/solc/solc\"\n preset: \"<< parameters.preset >>\"\n\n b_bytecode_win:\n parameters:\n preset:\n type: string\n <<: *base_win\n parallelism: 2 # For prepare_bytecode_report\n steps:\n # NOTE: For bytecode generation we need the input files to be byte-for-byte identical on all\n # platforms so line ending conversions must absolutely be disabled.\n - run: git config --global core.autocrlf false\n - checkout\n - run:\n name: Force install python3.12\n command: choco install python312 --pre --force\n - run:\n name: Create a symlink for python3\n command: ln -s /c/ProgramData/chocolatey/bin/python3.12 /c/ProgramData/chocolatey/bin/python3\n - attach_workspace:\n at: build\n - prepare_bytecode_report:\n label: \"windows\"\n binary_type: native\n binary_path: \"build/solc/Release/solc.exe\"\n preset: \"<< parameters.preset >>\"\n\n b_bytecode_ubu_arm:\n parameters:\n preset:\n type: string\n <<: *base_ubuntu2404_arm_medium\n parallelism: 2 # For prepare_bytecode_report\n steps:\n - checkout\n - attach_workspace:\n at: build\n - prepare_bytecode_report:\n label: \"ubuntu_arm\"\n binary_type: native\n binary_path: \"build/solc/solc-static-linux-arm\"\n preset: \"<< parameters.preset >>\"\n\n b_bytecode_ems:\n parameters:\n preset:\n type: string\n <<: *base_node_small\n steps:\n - checkout\n - attach_workspace:\n at: emscripten_build/libsolc\n - prepare_bytecode_report:\n label: \"emscripten\"\n binary_type: solcjs\n binary_path: \"emscripten_build/libsolc/soljson.js\"\n preset: \"<< parameters.preset >>\"\n\n t_bytecode_compare:\n <<: *base_ubuntu2404_small\n environment:\n <<: *base_ubuntu2404_small_env\n <<: *bytecode_compare_env_presets\n steps:\n - checkout\n - attach_workspace:\n at: .\n - run: .circleci/compare_bytecode_reports.sh $PRESETS\n - store_artifacts:\n # NOTE: store_artifacts does not support the 'when' attribute.\n # Fortunately when the artifact does not exist it just says \"No artifact files found\" and ignores it.\n path: bytecode-reports-*.zip\n - matrix_notify_failure_unless_pr\n\n c_release_binaries:\n <<: *base_ubuntu2404\n steps:\n - checkout\n - attach_workspace:\n at: workspace\n - run:\n name: Gather and rename binaries from dependent jobs\n command: |\n mkdir github/\n cp workspace/solc/solc-static-linux github/solc-static-linux\n cp workspace/solc/solc-static-linux-arm github/solc-static-linux-arm\n cp workspace/build/solc/solc github/solc-macos\n cp workspace/solc/Release/solc.exe github/solc-windows.exe\n cp workspace/soljson.js github/soljson.js\n\n cd github/\n tar --create --file ../github-binaries.tar *\n - store_artifacts:\n path: github-binaries.tar\n - run:\n name: Rename binaries to solc-bin naming convention\n command: |\n full_version=$(\n github/solc-static-linux --version |\n sed -En 's/^Version: ([0-9.]+.*\\+commit\\.[0-9a-f]+(\\.mod)?).*$/\\1/p'\n )\n\n mkdir -p solc-bin/{linux-amd64,linux-arm64,macosx-amd64,windows-amd64,bin}\n\n mv github/solc-static-linux-arm \"solc-bin/linux-arm64/solc-linux-arm64-v${full_version}\"\n mv github/solc-static-linux \"solc-bin/linux-amd64/solc-linux-amd64-v${full_version}\"\n mv github/solc-macos \"solc-bin/macosx-amd64/solc-macosx-amd64-v${full_version}\"\n mv github/solc-windows.exe \"solc-bin/windows-amd64/solc-windows-amd64-v${full_version}.exe\"\n mv github/soljson.js \"solc-bin/bin/soljson-v${full_version}.js\"\n\n cd solc-bin/\n tar --create --file ../solc-bin-binaries.tar *\n - store_artifacts:\n path: solc-bin-binaries.tar\n - matrix_notify_failure_unless_pr\n - matrix_notify_release_unless_pr\n\n c_source_tarball:\n <<: *base_ubuntu2404_small\n steps:\n - checkout\n - setup_prerelease\n - run: scripts/create_source_tarball.sh\n - store_artifacts:\n path: upload/\n - matrix_notify_failure_unless_pr\n - matrix_notify_release_unless_pr\n\n b_alpine_docker:\n <<: *base_cimg_small\n steps:\n - setup_remote_docker:\n # Always build from scratch to use current packages.\n # This job is only meant to run nightly so build time is not an issue.\n docker_layer_caching: false\n - checkout\n - run:\n name: Disable partial clone and fetch all objects\n command: |\n git config remote.origin.promisor false\n git config --unset remote.origin.partialclonefilter\n git fetch --refetch origin\n - run:\n name: Build and tag the container\n command: scripts/docker_deploy_manual.sh develop \"file://$PWD\" --no-push\n - run:\n name: Smoke test\n command: docker run --pull=never ghcr.io/argotorg/solc:build-alpine --version\n - matrix_notify_failure_unless_pr\n\nworkflows:\n version: 2\n\n main:\n jobs:\n # basic checks\n - chk_spelling: *requires_nothing\n - chk_coding_style: *requires_nothing\n # DISABLED FOR 0.6.0 - chk_docs_examples: *requires_nothing\n - chk_buglist: *requires_nothing\n - chk_proofs: *requires_nothing\n - chk_pylint: *requires_nothing\n - chk_errorcodes: *requires_nothing\n - chk_antlr_grammar: *requires_nothing\n - chk_docs_pragma_min_version: *requires_nothing\n - t_ubu_pyscripts: *requires_nothing\n - t_win_pyscripts: *requires_nothing\n\n # build-only\n - b_docs: *requires_nothing\n - b_ubu_ossfuzz: *requires_nothing\n\n # build and test with minimum supported versions of dependencies\n - b_ubu_min_req_clang: *requires_nothing\n - b_ubu_min_req: *requires_nothing\n - t_ubu_min_req_soltest:\n <<: *on_all_tags_and_branches\n requires:\n - b_ubu_min_req\n\n # OS/X build and tests\n - b_osx: *requires_nothing\n - t_osx_cli: *requires_b_osx\n - t_osx_soltest: *requires_b_osx\n\n # ArchLinux build and tests\n - b_archlinux: *requires_nothing\n - t_archlinux_soltest: *requires_b_archlinux\n\n # Static build\n - b_ubu_static: *requires_nothing\n - b_ubu_static_arm: *requires_nothing\n\n # Ubuntu build and tests\n - b_ubu: *requires_nothing\n - t_ubu_cli: *requires_b_ubu\n - t_ubu_arm_cli: *requires_b_ubu_static_arm\n - t_ubu_locale: *requires_b_ubu\n - t_ubu_soltest: *requires_b_ubu\n - t_ubu_arm_soltest: *requires_b_ubu_static_arm\n - b_ubu_clang: *requires_nothing\n - t_ubu_clang_soltest: *requires_b_ubu_clang\n - t_ubu_lsp: *requires_b_ubu\n\n # Ubuntu fake release build and tests\n - b_ubu_force_release: *requires_nothing\n - t_ubu_force_release_cli: *requires_b_ubu_force_release\n - t_ubu_force_release_soltest_all: *requires_b_ubu_force_release\n\n # Emscripten build and tests that take 15 minutes or less\n - b_ems: *requires_nothing\n - t_ems_solcjs: *requires_b_ems\n - t_ems_ext_edr: *requires_b_ems\n\n - t_ext: *job_ems_compile_ext_colony\n\n - t_ext: *job_native_compile_ext_gnosis\n - t_ext: *job_native_test_ext_zeppelin\n - t_ext: *job_native_test_ext_ens\n - t_ext: *job_native_test_ext_yield_liquidator\n - t_ext: *job_native_test_ext_uniswap\n - t_ext: *job_native_test_ext_prb_math\n - t_ext: *job_native_test_ext_elementfi\n - t_ext: *job_native_test_ext_brink\n - t_ext: *job_native_compile_ext_gp2\n - t_ext: *job_native_compile_ext_euler\n - t_ext: *job_native_compile_ext_pool_together\n # TODO: Dropping the external tests below since they are based on old forks and\n # fail after update the default evm version to cancun.\n #- t_ext: *job_native_compile_ext_trident\n #- t_ext: *job_native_compile_ext_chainlink\n #- t_ext: *job_native_compile_ext_bleeps\n\n - t_ethdebug_output_validity:\n <<: *requires_b_ubu_static\n\n - c_ext_benchmarks:\n <<: *requires_nothing\n requires:\n - t_ems_compile_ext_colony\n - t_native_compile_ext_gnosis\n - t_native_test_ext_zeppelin\n - t_native_test_ext_ens\n - t_native_test_ext_yield_liquidator\n - t_native_test_ext_uniswap\n - t_native_test_ext_elementfi\n - t_native_test_ext_brink\n - t_native_compile_ext_gp2\n # TODO: Dropping prb-math from the benchmarks since it is not implemented yet\n # in the new Foundry external testing infrastructure.\n # - t_native_test_ext_prb_math\n - t_native_compile_ext_euler\n - t_native_compile_ext_pool_together\n # TODO: Dropping the external tests below since they are based on old forks and\n # fail after update the default evm version to cancun.\n #- t_native_compile_ext_trident\n #- t_native_compile_ext_chainlink\n #- t_native_compile_ext_bleeps\n\n # Windows build and tests\n - b_win: *requires_nothing\n - t_win_soltest: *requires_b_win\n\n # Bytecode comparison:\n - b_bytecode_ubu_static:\n <<: *on_all_tags_and_branches\n matrix: *bytecode_compare_preset_matrix\n requires:\n - b_ubu_static\n - b_bytecode_ubu:\n <<: *on_all_tags_and_branches\n matrix: *bytecode_compare_preset_matrix\n requires:\n - b_ubu\n - b_bytecode_ubu_arm:\n <<: *on_all_tags_and_branches\n matrix: *bytecode_compare_preset_matrix\n requires:\n - b_ubu_static_arm\n - b_bytecode_win:\n <<: *on_all_tags_and_branches\n matrix: *bytecode_compare_preset_matrix\n requires:\n - b_win\n - b_bytecode_osx:\n <<: *on_all_tags_and_branches\n matrix: *bytecode_compare_preset_matrix\n requires:\n - b_osx\n - b_bytecode_osx_intel:\n <<: *on_all_tags_and_branches\n matrix: *bytecode_compare_preset_matrix\n requires:\n - b_osx\n - b_bytecode_ems:\n <<: *on_all_tags_and_branches\n matrix: *bytecode_compare_preset_matrix\n requires:\n - b_ems\n - t_bytecode_compare:\n <<: *on_all_tags_and_branches\n requires:\n - b_bytecode_ubu_static\n - b_bytecode_ubu\n - b_bytecode_ubu_arm\n - b_bytecode_win\n - b_bytecode_osx\n - b_bytecode_osx_intel\n - b_bytecode_ems\n\n # Final artifacts\n - c_release_binaries:\n <<: *on_version_tags\n requires:\n - b_ubu_static_arm\n - b_ubu_static\n - b_osx\n - b_win\n - b_ems\n - c_source_tarball: *requires_nothing\n\n nightly:\n\n triggers:\n - schedule:\n cron: \"0 0 * * *\"\n <<: *on_develop\n\n jobs:\n # ASan build and tests\n - b_ubu_asan: *requires_nothing\n - b_ubu_san_clang: *job_b_ubu_asan_clang\n - t_ubu_asan_soltest: *requires_b_ubu_asan\n - t_ubu_asan_clang_soltest: *requires_b_ubu_asan_clang\n - t_ubu_asan_cli: *requires_b_ubu_asan\n\n # UBSan build and tests\n - b_ubu_san_clang: *job_b_ubu_ubsan_clang\n - t_ubu_ubsan_clang_soltest: *requires_b_ubu_ubsan_clang\n - t_ubu_ubsan_clang_cli: *requires_b_ubu_ubsan_clang\n\n # Deprecated EVM versions tests\n - b_ubu: *requires_nothing\n - t_ubu_soltest_low_priority_evm_versions: *requires_b_ubu\n\n # Build in a Docker container (on Alpine Linux)\n - b_alpine_docker: *requires_nothing\n\n nightly-ossfuzz:\n\n triggers:\n - schedule:\n cron: \"0 0 * * *\"\n <<: *on_develop\n\n jobs:\n # OSSFUZZ builds and (regression) tests\n - b_ubu_ossfuzz: *requires_nothing\n - t_ubu_ossfuzz: *requires_b_ubu_ossfuzz\n" }, { "path": ".circleci/osx_install_dependencies.sh", "content": "#! /bin/bash\n#------------------------------------------------------------------------------\n# Bash script to install osx dependencies\n#\n# The documentation for solidity is hosted at:\n#\n# https://docs.soliditylang.org\n#\n# ------------------------------------------------------------------------------\n# This file is part of solidity.\n#\n# solidity is free software: you can redistribute it and/or modify\n# it under the terms of the GNU General Public License as published by\n# the Free Software Foundation, either version 3 of the License, or\n# (at your option) any later version.\n#\n# solidity is distributed in the hope that it will be useful,\n# but WITHOUT ANY WARRANTY; without even the implied warranty of\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n# GNU General Public License for more details.\n#\n# You should have received a copy of the GNU General Public License\n# along with solidity. If not, see \n#\n# (c) 2016-2019 solidity contributors.\n# ------------------------------------------------------------------------------\n\n# note that the following directories may be cached by circleci:\n# - /usr/local\n# - /opt/homebrew\n\nset -eu\n\nfunction validate_checksum {\n local package=\"$1\"\n local expected_checksum=\"$2\"\n\n local actual_checksum\n actual_checksum=$(sha256sum \"$package\")\n if [[ $actual_checksum != \"${expected_checksum} ${package}\" ]]\n then\n >&2 echo \"ERROR: Wrong checksum for package $package.\"\n >&2 echo \"Actual: $actual_checksum\"\n >&2 echo \"Expected: $expected_checksum\"\n exit 1\n fi\n}\n\nif [ ! -f /usr/local/lib/libz3.a ] # if this file does not exists (cache was not restored), rebuild dependencies\nthen\n brew update\n brew upgrade\n brew install cmake\n brew install ccache\n brew install wget\n brew install coreutils\n brew install diffutils\n brew install grep\n # JRE is required to run eldarica solver\n brew install openjdk@11\n brew install unzip\n\n # boost\n boost_version=\"1.84.0\"\n boost_package=\"boost_${boost_version//./_}.tar.bz2\"\n boost_dir=\"boost_${boost_version//./_}\"\n wget \"https://archives.boost.io/release/$boost_version/source/$boost_package\"\n tar xf \"$boost_package\"\n rm \"$boost_package\"\n cd \"$boost_dir\"\n ./bootstrap.sh --with-toolset=clang --with-libraries=thread,system,filesystem,program_options,serialization,test\n # the default number of jobs that b2 is taking, is the number of detected available CPU threads.\n # install boost to /opt/boost, to use it in CMake, specify Boost_ROOT\n sudo ./b2 -a address-model=64 architecture=arm+x86 --prefix=/opt/boost install\n cd ..\n sudo rm -rf \"$boost_dir\"\n\n # eldarica\n eldarica_version=\"2.1\"\n wget \"https://github.com/uuverifiers/eldarica/releases/download/v${eldarica_version}/eldarica-bin-${eldarica_version}.zip\" -O /tmp/eld_binaries.zip\n validate_checksum /tmp/eld_binaries.zip 0ac43f45c0925383c9d2077f62bbb515fd792375f3b2b101b30c9e81dcd7785c\n unzip /tmp/eld_binaries.zip -d /tmp\n sudo mv /tmp/eldarica/{eld,eld-client,target,eldEnv} /usr/local/bin\n rm -rf /tmp/{eldarica,eld_binaries.zip}\n\n #cvc5\n cvc5_version=\"1.2.0\"\n cvc5_archive_name=\"cvc5-macOS-arm64-static\"\n wget \"https://github.com/cvc5/cvc5/releases/download/cvc5-${cvc5_version}/${cvc5_archive_name}.zip\" -O /tmp/cvc5.zip\n validate_checksum /tmp/cvc5.zip 57d2d4855af3f3865110a254e415098b4e150a655f297010e27eb292f48f7da7\n sudo unzip -j /tmp/cvc5.zip \"${cvc5_archive_name}/bin/cvc5\" -d /usr/local/bin\n rm -f /tmp/cvc5.zip\n\n # z3\n z3_version=\"4.13.3\"\n z3_dir=\"z3-z3-$z3_version\"\n z3_package=\"z3-$z3_version.tar.gz\"\n wget \"https://github.com/Z3Prover/z3/archive/refs/tags/$z3_package\"\n validate_checksum \"$z3_package\" f59c9cf600ea57fb64ffeffbffd0f2d2b896854f339e846f48f069d23bc14ba0\n tar xf \"$z3_package\"\n rm \"$z3_package\"\n cd \"$z3_dir\"\n mkdir build\n cd build\n cmake -DCMAKE_OSX_ARCHITECTURES:STRING=\"x86_64;arm64\" -DZ3_BUILD_LIBZ3_SHARED=false ..\n make -j \"$(nproc)\"\n sudo make install\n cd ../..\n rm -rf \"$z3_dir\"\n\n # evmone\n evmone_version=\"0.16.0\"\n evmone_package=\"evmone-${evmone_version}-darwin-arm64.tar.gz\"\n wget \"https://github.com/ipsilon/evmone/releases/download/v${evmone_version}/${evmone_package}\"\n validate_checksum \"$evmone_package\" d26bcf7ada6c712b669ee70cbd8b534f80dadb6207fa15e15d1517d2b6823aa8\n sudo tar xzpf \"$evmone_package\" -C /usr/local\n rm \"$evmone_package\"\nfi\n" }, { "path": ".circleci/parallel_bytecode_report.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n#------------------------------------------------------------------------------\n# Splits all test source code into multiple files, generates bytecode and metadata\n# for each file and combines it into a single report.txt file.\n#\n# The script is meant to be executed in CI on all supported platforms. All generated\n# reports must be identical for a given compiler version.\n#\n# ------------------------------------------------------------------------------\n# This file is part of solidity.\n#\n# solidity is free software: you can redistribute it and/or modify\n# it under the terms of the GNU General Public License as published by\n# the Free Software Foundation, either version 3 of the License, or\n# (at your option) any later version.\n#\n# solidity is distributed in the hope that it will be useful,\n# but WITHOUT ANY WARRANTY; without even the implied warranty of\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n# GNU General Public License for more details.\n#\n# You should have received a copy of the GNU General Public License\n# along with solidity. If not, see \n#\n# (c) 2023 solidity contributors.\n#------------------------------------------------------------------------------\n\n(( $# == 4 )) || { >&2 echo \"Wrong number of arguments.\"; exit 1; }\nlabel=\"$1\"\nbinary_type=\"$2\"\nbinary_path=\"$3\" # This path must be absolute\npreset=\"$4\"\n\n[[ $binary_type == native || $binary_type == \"osx_intel\" || $binary_type == solcjs ]] || { >&2 echo \"Invalid binary type: ${binary_type}\"; exit 1; }\n\n# NOTE: Locale affects the order of the globbed files.\nexport LC_ALL=C\n\nmkdir test-cases/\ncd test-cases/\n\necho \"Preparing input files\"\npython3 ../scripts/isolate_tests.py ../test/\n\nif [[ $binary_type == native || $binary_type == \"osx_intel\" ]]; then\n interface=$(echo -e \"standard-json\\ncli\" | circleci tests split)\n echo \"Selected interface: ${interface}\"\n\n echo \"Generating bytecode reports\"\n python3 ../scripts/bytecodecompare/prepare_report.py \\\n \"$binary_path\" \\\n --interface \"$interface\" \\\n --preset \"$preset\" \\\n --execution-arch \"$binary_type\" \\\n --report-file \"../bytecode-report-${label}-${interface}-${preset}.txt\"\nelse\n echo \"Installing solc-js\"\n git clone --depth 1 https://github.com/argotorg/solc-js.git solc-js\n cp \"$binary_path\" solc-js/soljson.js\n\n cd solc-js/\n npm install\n npm run build\n\n cd ..\n npm install ./solc-js/dist\n\n cp ../scripts/bytecodecompare/prepare_report.js .\n\n echo \"Generating bytecode reports\"\n # shellcheck disable=SC2035\n ./prepare_report.js \\\n --preset \"$preset\" \\\n *.sol --report-file \"../bytecode-report-${label}-${preset}.txt\"\nfi\n" }, { "path": ".circleci/parallel_cli_tests.py", "content": "#!/usr/bin/env python3\n\nimport subprocess\nimport sys\n\n# Slowest CLI tests, whose execution takes time on the order of minutes (as of June 2023).\n# When adding/removing items here, remember to update `parallelism` value in jobs that run this script.\n# TODO: We should switch to time-based splitting but that requires JUnit XML report support in cmdlineTests.sh.\ntests_to_run_in_parallel = [\n '~ast_import_export', # ~7 min\n '~evmasm_import_export', # ~5 min\n '~ast_export_with_stop_after_parsing', # ~4 min\n '~soljson_via_fuzzer', # ~3 min\n '~via_ir_equivalence', # ~1 min\n '~compilation_tests', # ~1 min\n '~documentation_examples', # ~1 min\n '*', # This item represents all the remaining tests\n]\n\n# Ask CircleCI to select a subset of tests for this parallel execution.\n# If `parallelism` in CI config is set correctly, we should get just one but we can handle any split.\nselected_tests = subprocess.check_output(\n ['circleci', 'tests', 'split'],\n input='\\n'.join(tests_to_run_in_parallel),\n encoding='ascii',\n).strip().split('\\n')\nselected_tests = set(selected_tests) - {''}\nexcluded_tests = set(tests_to_run_in_parallel) - selected_tests\nassert selected_tests.issubset(set(tests_to_run_in_parallel))\n\nif len(selected_tests) == 0:\n print(\"No tests to run.\")\n sys.exit(0)\n\nif '*' in selected_tests:\n filters = [arg for test_name in excluded_tests for arg in ['--exclude', test_name]]\nelse:\n filters = list(selected_tests)\n\ntry:\n subprocess.run(\n ['test/cmdlineTests.sh'] + filters,\n stdin=sys.stdin,\n stdout=sys.stdout,\n stderr=sys.stderr,\n check=True,\n )\nexcept subprocess.CalledProcessError as exception:\n sys.exit(exception)\n" }, { "path": ".circleci/soltest.ps1", "content": "$ErrorActionPreference = \"Stop\"\n\ncd \"$PSScriptRoot\\..\"\n\n.\\build\\solc\\Release\\solc.exe --version\nif ( -not $? ) { throw \"Cannot execute solc --version.\" }\n\nmkdir test_results\n.\\build\\test\\Release\\soltest.exe --color_output=no --show_progress=yes --logger=JUNIT,error,test_results/result.xml --logger=HRF,error,stdout -- --no-smt\nif ( -not $? ) { throw \"Unoptimized soltest run failed.\" }\n.\\build\\test\\Release\\soltest.exe --color_output=no --show_progress=yes --logger=JUNIT,error,test_results/result_opt.xml --logger=HRF,error,stdout -- --optimize --no-smt\nif ( -not $? ) { throw \"Optimized soltest run failed.\" }\n" }, { "path": ".circleci/soltest.sh", "content": "#!/usr/bin/env bash\n#------------------------------------------------------------------------------\n# Bash script to execute the Solidity tests by CircleCI.\n#\n# The documentation for solidity is hosted at:\n#\n# https://docs.soliditylang.org\n#\n# ------------------------------------------------------------------------------\n# Configuration Environment Variables:\n#\n# EVM=version_string Specifies EVM version to compile for (such as homestead, etc)\n# OPTIMIZE=1 Enables backend optimizer\n# ABI_ENCODER_V1=1 Forcibly enables ABI coder version 1\n# SOLTEST_FLAGS= Appends to default SOLTEST_ARGS\n#\n# ------------------------------------------------------------------------------\n# This file is part of solidity.\n#\n# solidity is free software: you can redistribute it and/or modify\n# it under the terms of the GNU General Public License as published by\n# the Free Software Foundation, either version 3 of the License, or\n# (at your option) any later version.\n#\n# solidity is distributed in the hope that it will be useful,\n# but WITHOUT ANY WARRANTY; without even the implied warranty of\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n# GNU General Public License for more details.\n#\n# You should have received a copy of the GNU General Public License\n# along with solidity. If not, see \n#\n# (c) 2016-2019 solidity contributors.\n# ------------------------------------------------------------------------------\nset -e\n\nOPTIMIZE=${OPTIMIZE:-\"0\"}\nEVM=${EVM:-\"invalid\"}\nEOF_VERSION=${EOF_VERSION:-0}\nCPUs=${CPUs:-3}\nREPODIR=\"$(realpath \"$(dirname \"$0\")/..\")\"\n\nIFS=\" \" read -r -a BOOST_TEST_ARGS <<< \"$BOOST_TEST_ARGS\"\nIFS=\" \" read -r -a SOLTEST_FLAGS <<< \"$SOLTEST_FLAGS\"\n\n# TODO: [EOF] These won't pass on EOF yet. Reenable them when the implementation is complete.\nEOF_EXCLUDES=(\n --run_test='!yulStackLayout/literal_loop'\n)\n\n# shellcheck source=scripts/common.sh\nsource \"${REPODIR}/scripts/common.sh\"\n# Test result output directory (CircleCI is reading test results from here)\nmkdir -p test_results\n\n# in case we run with ASAN enabled, we must increase stack size.\nulimit -s 16384\n\nget_logfile_basename() {\n local run=\"$1\"\n local filename=\"${EVM}\"\n test \"${OPTIMIZE}\" = \"1\" && filename=\"${filename}_opt\"\n test \"${ABI_ENCODER_V1}\" = \"1\" && filename=\"${filename}_abiv1\"\n (( EOF_VERSION != 0 )) && filename=\"${filename}_eofv${EOF_VERSION}\"\n filename=\"${filename}_${run}\"\n\n echo -ne \"${filename}\"\n}\n\n[ -z \"$CIRCLE_NODE_TOTAL\" ] || [ \"$CIRCLE_NODE_TOTAL\" = 0 ] && CIRCLE_NODE_TOTAL=1\n[ -z \"$CIRCLE_NODE_INDEX\" ] && CIRCLE_NODE_INDEX=0\n[ -z \"$INDEX_SHIFT\" ] && INDEX_SHIFT=0\n\n# Multiply by a prime number to get better spread, just in case\n# long-running test cases are next to each other.\nCIRCLE_NODE_INDEX=$(((CIRCLE_NODE_INDEX + 23 * INDEX_SHIFT) % CIRCLE_NODE_TOTAL))\n\nPIDs=()\nfor run in $(seq 0 $((CPUs - 1)))\ndo\n BOOST_TEST_ARGS_RUN=(\n \"--color_output=no\"\n \"--show_progress=yes\"\n \"--logger=JUNIT,error,test_results/$(get_logfile_basename \"$((CPUs * CIRCLE_NODE_INDEX + run))\").xml\"\n \"--logger=HRF,error,stdout\"\n \"${BOOST_TEST_ARGS[@]}\"\n )\n (( EOF_VERSION != 0 )) && BOOST_TEST_ARGS_RUN+=(\"${EOF_EXCLUDES[@]}\")\n SOLTEST_ARGS=(\"--evm-version=$EVM\" \"${SOLTEST_FLAGS[@]}\")\n\n test \"${OPTIMIZE}\" = \"1\" && SOLTEST_ARGS+=(--optimize)\n test \"${ABI_ENCODER_V1}\" = \"1\" && SOLTEST_ARGS+=(--abiencoderv1)\n (( EOF_VERSION != 0 )) && SOLTEST_ARGS+=(--eof-version \"$EOF_VERSION\")\n\n BATCH_ARGS=(\"--batches\" \"$((CPUs * CIRCLE_NODE_TOTAL))\" \"--selected-batch\" \"$((CPUs * CIRCLE_NODE_INDEX + run))\")\n\n echo \"Running ${REPODIR}/build/test/soltest ${BOOST_TEST_ARGS_RUN[*]} -- ${SOLTEST_ARGS[*]}\"\n\n \"${REPODIR}/build/test/soltest\" -l test_suite \"${BOOST_TEST_ARGS_RUN[@]}\" -- \"${SOLTEST_ARGS[@]}\" \"${BATCH_ARGS[@]}\" &\n PIDs+=($!)\ndone\n\n# wait for individual processes to get their exit status\nfor pid in \"${PIDs[@]}\"\ndo\n wait \"$pid\"\ndone\n" }, { "path": ".circleci/soltest_all.sh", "content": "#! /bin/bash\n#------------------------------------------------------------------------------\n# Bash script to execute the Solidity tests by CircleCI.\n#\n# The documentation for solidity is hosted at:\n#\n# https://docs.soliditylang.org\n#\n# ------------------------------------------------------------------------------\n# This file is part of solidity.\n#\n# solidity is free software: you can redistribute it and/or modify\n# it under the terms of the GNU General Public License as published by\n# the Free Software Foundation, either version 3 of the License, or\n# (at your option) any later version.\n#\n# solidity is distributed in the hope that it will be useful,\n# but WITHOUT ANY WARRANTY; without even the implied warranty of\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n# GNU General Public License for more details.\n#\n# You should have received a copy of the GNU General Public License\n# along with solidity. If not, see \n#\n# (c) 2016-2019 solidity contributors.\n# ------------------------------------------------------------------------------\nset -e\n\nREPODIR=\"$(realpath \"$(dirname \"$0\")\"/..)\"\n\n# shellcheck source=scripts/common.sh\nsource \"${REPODIR}/scripts/common.sh\"\n\nDEFAULT_EVM_VALUES=(\n homestead\n constantinople\n istanbul\n berlin\n london\n paris\n shanghai\n cancun\n osaka\n)\nEVMS_WITH_EOF=(osaka)\n\n# Deserialize the EVM_VALUES array if it was provided as argument or\n# set EVM_VALUES to the default values.\nIFS=\" \" read -ra EVM_VALUES <<< \"${1:-${DEFAULT_EVM_VALUES[@]}}\"\n\nDEFAULT_EVM=osaka\nOPTIMIZE_VALUES=(0 1)\n# TODO: EOF is marked as experimental in evmone. Reenable when proper handling for that is added here.\nEOF_VERSIONS=(0)\n\n# Run for ABI encoder v1, without SMTChecker tests.\nEVM=\"${DEFAULT_EVM}\" \\\nOPTIMIZE=1 \\\nABI_ENCODER_V1=1 \\\nBOOST_TEST_ARGS=\"-t !smtCheckerTests\" \\\n\"${REPODIR}/.circleci/soltest.sh\"\n\n# We shift the batch index so that long-running tests\n# do not always run in the same executor for all EVM versions\nINDEX_SHIFT=0\nfor OPTIMIZE in \"${OPTIMIZE_VALUES[@]}\"\ndo\n for EVM in \"${EVM_VALUES[@]}\"\n do\n for EOF_VERSION in \"${EOF_VERSIONS[@]}\"\n do\n if (( EOF_VERSION > 0 )) && [[ ! \" ${EVMS_WITH_EOF[*]} \" == *\" $EVM \"* ]]; then\n continue\n fi\n\n ENFORCE_GAS_ARGS=\"\"\n [ \"${EVM}\" = \"${DEFAULT_EVM}\" ] && ENFORCE_GAS_ARGS=\"--enforce-gas-cost\"\n # Run SMTChecker tests only when OPTIMIZE == 0\n DISABLE_SMTCHECKER=\"\"\n [ \"${OPTIMIZE}\" != \"0\" ] && DISABLE_SMTCHECKER=\"-t !smtCheckerTests\"\n\n EVM=\"$EVM\" \\\n EOF_VERSION=\"$EOF_VERSION\" \\\n OPTIMIZE=\"$OPTIMIZE\" \\\n SOLTEST_FLAGS=\"$SOLTEST_FLAGS $ENFORCE_GAS_ARGS\" \\\n BOOST_TEST_ARGS=\"-t !@nooptions $DISABLE_SMTCHECKER\" \\\n INDEX_SHIFT=\"$INDEX_SHIFT\" \\\n \"${REPODIR}/.circleci/soltest.sh\"\n\n INDEX_SHIFT=$((INDEX_SHIFT + 1))\n done\n done\ndone\n" }, { "path": ".clang-format", "content": "# Formatting approximately used in Solidity's C++\n#\n# See https://clang.llvm.org/docs/ClangFormatStyleOptions.html\n# For an online formatter to test settings, see\n# https://zed0.co.uk/clang-format-configurator/\n# Note that clang-format cannot express the style that closing parentheses\n# behave similar to closing curly braces in a multi-line setting in that\n# they have to be on a line of their own at the same indentation level\n# as the opening part (aka \"dangling parenthesis\", see https://reviews.llvm.org/D33029).\n\nLanguage: Cpp\nBasedOnStyle: LLVM\nAccessModifierOffset: -4\nAlignAfterOpenBracket: AlwaysBreak\nAlignEscapedNewlines: Left\nAlwaysBreakAfterReturnType: None\nAlwaysBreakTemplateDeclarations: Yes\nBinPackArguments: false\nBinPackParameters: false\nBreakBeforeBinaryOperators: All\nBreakBeforeBraces: Allman\nColumnLimit: 120\nContinuationIndentWidth: 4\nFixNamespaceComments: false\nIndentWidth: 4\nKeepEmptyLinesAtTheStartOfBlocks: false\nMaxEmptyLinesToKeep: 2\nPenaltyBreakBeforeFirstCallParameter: 2000\nPointerAlignment: Left\nSpaceAfterCStyleCast: true\nSpaceAfterTemplateKeyword: false\nSpaceBeforeCtorInitializerColon: false\nSpaceBeforeInheritanceColon: false\nSpaceBeforeParens: ControlStatements\nSpaceBeforeRangeBasedForLoopColon: false\nTabWidth: 4\nUseTab: Always\n\n# Local Variables:\n# mode: yaml\n# End:\n" }, { "path": ".codespellrc", "content": "[codespell]\nskip = .git,deps,LICENSE,*.enc,Dockerfile*,codespell_whitelist.txt,codespell_ignored_lines.txt\nignore-words = scripts/codespell_whitelist.txt\nexclude-file = scripts/codespell_ignored_lines.txt\n" }, { "path": ".dockerignore", "content": "# out-of-tree builds usually go here. This helps improving performance of uploading\n# the build context to the docker image build server\n/build\n\n" }, { "path": ".editorconfig", "content": "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\ninsert_final_newline = true\ntrim_trailing_whitespace = true\n\n[*.{cpp,h}]\nindent_style = tab\nindent_size = 4\n\n[*.{py,rst,sh,yml}]\nindent_style = space\nindent_size = 4\n\n[*.{sol,yul}]\nindent_style = space\nindent_size = 4\n\n[*.{txt,cmake,json}]\nindent_style = tab\nindent_size = 4\n" }, { "path": ".gitattributes", "content": "*.sol linguist-language=Solidity\n" }, { "path": ".github/CODEOWNERS", "content": "/docs/style-guide.rst @fulldecent\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.md", "content": "---\nname: Bug Report\nabout: Problems, deficiencies, inaccuracies or crashes discovered on Solidity.\ntitle: ''\nlabels: 'bug :bug:'\nassignees: ''\n\n---\n\n\n\n## Description\n\n\n\n## Environment\n\n- Compiler version:\n- Compilation pipeline (legacy, IR, EOF):\n- Target EVM version (as per compiler settings):\n- Framework/IDE (e.g. Foundry, Hardhat, Remix):\n- EVM execution environment / backend / blockchain client:\n- Operating system:\n\n## Steps to Reproduce\n\n\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\ncontact_links:\n - name: Initiate a language design or feedback discussion\n url: https://forum.soliditylang.org\n about: Open a thread on the Solidity forum.\n" }, { "path": ".github/ISSUE_TEMPLATE/documentation_issue.md", "content": "---\nname: Documentation Issue\nabout: Corrections, improvements or requests for new content on Solidity's documentation.\ntitle: ''\nlabels: 'documentation :book:'\nassignees: ''\n\n---\n\n## Page\n\n\n\n## Abstract\n\n\n\n## Pull request\n\n\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.md", "content": "---\nname: Feature Request\nabout: Ideas, comments or messages asking for a particular functionality to be added\n to Solidity.\ntitle: ''\nlabels: feature\nassignees: ''\n\n---\n\n\n\n## Abstract\n\n\n\n## Motivation\n\n\n\n## Specification\n\n\n\n## Backwards Compatibility\n\n\n" }, { "path": ".github/workflows/buildpack-deps.yml", "content": "name: buildpack-deps\n\npermissions:\n packages: write\n pull-requests: write\n\non:\n pull_request:\n branches: [ develop ]\n paths:\n - 'scripts/docker/buildpack-deps/Dockerfile.emscripten'\n - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu.clang.ossfuzz'\n - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2404'\n - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2404.clang'\n - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2404.arm'\n\njobs:\n buildpack-deps:\n runs-on: ${{ matrix.runs-on }}\n\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n DOCKER_REPOSITORY: ghcr.io/argotorg/solidity-buildpack-deps\n IMAGE_NAME: buildpack-deps\n\n strategy:\n fail-fast: false\n matrix:\n include:\n - image_variant: emscripten\n runs-on: ubuntu-latest\n - image_variant: ubuntu.clang.ossfuzz\n runs-on: ubuntu-latest\n - image_variant: ubuntu2404\n runs-on: ubuntu-latest\n - image_variant: ubuntu2404.clang\n runs-on: ubuntu-latest\n - image_variant: ubuntu2404.arm\n runs-on: ubuntu-24.04-arm\n\n steps:\n - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0\n with:\n fetch-depth: 0\n\n - name: Log in to GitHub Container Registry\n uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0\n with:\n registry: ghcr.io\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Upgrade ${{ env.IMAGE_NAME }}-${{ matrix.image_variant }}\n run: |\n scripts/ci/docker_upgrade.sh ${{ env.IMAGE_NAME }} ${{ matrix.image_variant }} ${{ env.DOCKER_REPOSITORY }}\n\n - name: comment PR\n if: \"env.DOCKER_IMAGE\"\n uses: thollander/actions-comment-pull-request@24bffb9b452ba05a4f3f77933840a6a841d1b32b # v3.0.1\n with:\n message: \"`${{ env.DOCKER_IMAGE }} ${{ env.DOCKER_REPO_DIGEST }}`.\"\n" }, { "path": ".github/workflows/stale.yml", "content": "name: Check stale pull requests\n\non:\n workflow_dispatch:\n schedule:\n - cron: '0 12 * * *'\n\npermissions:\n pull-requests: write\n\nenv:\n # NOTE: We set the parameters below to -1, so issues will never be marked as stale or closed automatically.\n BEFORE_ISSUE_STALE: -1\n BEFORE_ISSUE_CLOSE: -1\n BEFORE_PR_STALE: 14\n BEFORE_PR_CLOSE: 7\n\njobs:\n stale:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/stale@3a9db7e6a41a89f618792c92c0e97cc736e1b13f # v10.0.0\n with:\n debug-only: false\n days-before-issue-stale: ${{ env.BEFORE_ISSUE_STALE }}\n days-before-issue-close: ${{ env.BEFORE_ISSUE_CLOSE }}\n ascending: true\n stale-pr-message: |\n This pull request is stale because it has been open for ${{ env.BEFORE_PR_STALE }} days with no activity.\n It will be closed in ${{ env.BEFORE_PR_CLOSE }} days unless the `stale` label is removed.\n close-pr-message: |\n This pull request was closed due to a lack of activity for ${{ env.BEFORE_PR_CLOSE }} days after it was stale.\n stale-pr-label: stale\n close-pr-label: closed-due-inactivity\n days-before-pr-stale: ${{ env.BEFORE_PR_STALE }}\n days-before-pr-close: ${{ env.BEFORE_PR_CLOSE }}\n exempt-pr-labels: 'external contribution :star:,roadmap,epic'\n exempt-draft-pr: false\n exempt-all-milestones: true\n remove-stale-when-updated: true\n operations-per-run: 256\n" }, { "path": ".github/workflows/welcome-external-pr.yml", "content": "name: External contributor greeter\n\non:\n pull_request_target:\n types:\n - opened\n\npermissions:\n pull-requests: write\n contents: read\n\nenv:\n DRY_RUN: false\n\njobs:\n comment-external-pr:\n runs-on: ubuntu-latest\n steps:\n # Note: this step requires that the INTERNAL_CONTRIBUTORS environment variable\n # is already defined in the repository with the current json list of internal contributors.\n - name: Comment on external contribution PR\n if: \"!contains(fromJSON(vars.INTERNAL_CONTRIBUTORS), github.event.pull_request.user.login)\"\n env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n PR: ${{ github.event.pull_request.html_url }}\n run: |\n echo \"Commenting in a newly submitted or reopened external PR: $PR\"\n if [[ $DRY_RUN == 'false' ]]; then\n gh pr edit \"$PR\" --add-label \"external contribution :star:\"\n comment_body=(\n \"Thank you for your contribution to the Solidity compiler! A team member will follow up shortly.\"\n \"\\n\\n\"\n \"If you haven't read our [contributing guidelines](https://docs.soliditylang.org/en/latest/contributing.html) and our \"\n \"[review checklist](https://github.com/argotorg/solidity/blob/develop/ReviewChecklist.md) before, \"\n \"please do it now, this makes the reviewing process and accepting your contribution smoother.\"\n \"\\n\\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 \"\n \"[#solidity-dev](https://matrix.to/#/#ethereum_solidity-dev:gitter.im) channel on Matrix.\"\n )\n gh pr comment $PR --body \"$(IFS='' ; echo -e \"${comment_body[*]}\")\"\n fi\n" }, { "path": ".gitignore", "content": "/commit_hash.txt\n/prerelease.txt\n\n# Compiled Object files\n*.slo\n*.lo\n*.o\n*.obj\n*.pyc\n__pycache__/\n\n# Precompiled Headers\n*.gch\n*.pch\n\n# Compiled Dynamic libraries\n*.so\n*.dylib\n*.dll\n\n# Compiled Static libraries\n*.lai\n*.la\n*.a\n*.lib\n\n# ignore git mergetool backup files\n*.orig\n\n# Executables\n*.exe\n*.out\n*.app\n\n# Build directory\n/cmake-build-*/\n/build*/\nemscripten_build/\n/docs/_build/\n/docs/_static/robots.txt\n/deps/\n\n# Reports and benchmarks\n/reports/\n/benchmarks/\n\n# vim stuff\n[._]*.sw[a-p]\n[._]sw[a-p]\n\n# emacs stuff\n*~\n\n# IDE files\n/.idea/\n/.vscode/\n/browse.VC.db\n/CMakeLists.txt.user\n/CMakeSettings.json\n/.vs\n/.cproject\n/.project\n\n# OS specific local files\n.DS_Store\nThumbs.db\n\n# AI tooling\n/.claude/\n" }, { "path": ".gitmodules", "content": "[submodule \"deps/nlohmann-json\"]\n\tpath = deps/nlohmann-json\n\turl = https://github.com/nlohmann/json.git\n[submodule \"deps/range-v3\"]\n\tpath = deps/range-v3\n\turl = https://github.com/ericniebler/range-v3.git\n[submodule \"deps/fmtlib\"]\n\tpath = deps/fmtlib\n\turl = https://github.com/fmtlib/fmt.git\n" }, { "path": ".readthedocs.yml", "content": "version: 2\n\nbuild:\n os: ubuntu-24.04\n tools:\n python: \"3.13\"\n\nsphinx:\n builder: html\n configuration: docs/conf.py\n\nformats:\n - pdf\n - epub\n\npython:\n install:\n - requirements: docs/requirements.txt\n" }, { "path": "CMakeLists.txt", "content": "cmake_minimum_required(VERSION 3.13.0)\n\nset(CMAKE_EXPORT_COMPILE_COMMANDS ON)\n\nset(ETH_CMAKE_DIR \"${CMAKE_CURRENT_LIST_DIR}/cmake\" CACHE PATH \"The path to the cmake directory\")\nlist(APPEND CMAKE_MODULE_PATH ${ETH_CMAKE_DIR})\n\n# Set the build type, if none was specified.\nif(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)\n\tif(EXISTS \"${PROJECT_SOURCE_DIR}/.git\")\n\t\tset(DEFAULT_BUILD_TYPE \"RelWithDebInfo\")\n\telse()\n\t\tset(DEFAULT_BUILD_TYPE \"Release\")\n\tendif()\n\tset(CMAKE_BUILD_TYPE \"${DEFAULT_BUILD_TYPE}\" CACHE STRING \"Choose the type of build, options are: Debug Release RelWithDebInfo MinSizeRel\" FORCE)\n\tset_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS \"Debug\" \"Release\" \"RelWithDebInfo\" \"MinSizeRel\")\nendif()\n\ninclude(EthToolchains)\n\n# Set cmake_policies\ninclude(EthPolicy)\neth_policy()\n\n# project name and version should be set after cmake_policy CMP0048\nset(PROJECT_VERSION \"0.8.35\")\n# OSX target needed in order to support std::visit\nset(CMAKE_OSX_DEPLOYMENT_TARGET \"10.14\")\nproject(solidity VERSION ${PROJECT_VERSION} LANGUAGES C CXX)\n\ninclude(TestBigEndian)\nTEST_BIG_ENDIAN(IS_BIG_ENDIAN)\nif (IS_BIG_ENDIAN)\n\tmessage(FATAL_ERROR \"${PROJECT_NAME} currently does not support big endian systems.\")\nendif()\n\noption(SOLC_LINK_STATIC \"Link solc executable statically on supported platforms\" OFF)\noption(SOLC_STATIC_STDLIBS \"Link solc against static versions of libgcc and libstdc++ on supported platforms\" OFF)\noption(STRICT_Z3_VERSION \"Require the exact version of Z3 solver expected by our test suite.\" ON)\noption(PEDANTIC \"Enable extra warnings and pedantic build flags. Treat all warnings as errors.\" ON)\noption(PROFILE_OPTIMIZER_STEPS \"Output performance metrics for the optimiser steps.\" OFF)\noption(\n\tIGNORE_VENDORED_DEPENDENCIES\n\t\"Ignore libraries provided as submodules of the repository and allow CMake to look for \\\nthem in the typical locations, including system-wide dirs.\"\n\tOFF\n)\noption(\n\tONLY_BUILD_SOLIDITY_LIBRARIES\n\t\"Only build library targets that can be statically linked against. Do not build executables or tests.\"\n\tOFF\n)\nmark_as_advanced(PROFILE_OPTIMIZER_STEPS)\nmark_as_advanced(IGNORE_VENDORED_DEPENDENCIES)\nmark_as_advanced(ONLY_BUILD_SOLIDITY_LIBRARIES)\n\n# Setup cccache.\ninclude(EthCcache)\n\n# Let's find our dependencies\ninclude(EthDependencies)\nif (NOT IGNORE_VENDORED_DEPENDENCIES)\n include(fmtlib)\n include(nlohmann-json)\n include(range-v3)\nelse ()\n message(WARNING \"-- Ignoring vendored dependencies. Will use installed versions if found. Versions may differ from the ones the compiler was tested with. Make sure to run the test suite and thoroughly test the resulting binaries before using them in production.\")\n find_package(fmt REQUIRED)\n find_package(nlohmann_json REQUIRED)\n find_package(range-v3 REQUIRED)\nendif()\n\nfind_package(Threads)\n\nif(NOT PEDANTIC)\n message(WARNING \"-- Pedantic build flags turned off. Warnings will not make compilation fail. This is NOT recommended in development builds.\")\nendif()\n\nif (PROFILE_OPTIMIZER_STEPS)\n add_definitions(-DPROFILE_OPTIMIZER_STEPS)\nendif()\n\n# Figure out what compiler and system are we using\ninclude(EthCompilerSettings)\n\n# Include utils\ninclude(EthUtils)\n\n# Create license.h from LICENSE.txt and template\n# Converting to char array is required due to MSVC's string size limit.\nfile(READ ${PROJECT_SOURCE_DIR}/LICENSE.txt LICENSE_TEXT HEX)\nstring(REGEX MATCHALL \"..\" LICENSE_TEXT \"${LICENSE_TEXT}\")\nstring(REGEX REPLACE \";\" \",\\n\\t0x\" LICENSE_TEXT \"${LICENSE_TEXT}\")\nset(LICENSE_TEXT \"0x${LICENSE_TEXT}\")\n\nconfigure_file(\"${PROJECT_SOURCE_DIR}/cmake/templates/license.h.in\" include/license.h)\n\ninclude(EthOptions)\nconfigure_project(TESTS)\n\nif(EMSCRIPTEN)\n set(TESTED_Z3_VERSION \"4.13.3\")\n set(MINIMUM_Z3_VERSION \"4.8.16\")\n find_package(Z3)\n if (${Z3_FOUND})\n add_definitions(-DEMSCRIPTEN_BUILD)\n if (${STRICT_Z3_VERSION})\n if (NOT (\"${Z3_VERSION_STRING}\" VERSION_EQUAL ${TESTED_Z3_VERSION}))\n message(\n FATAL_ERROR\n \"SMTChecker tests require Z3 ${TESTED_Z3_VERSION} for all tests to pass.\\n\"\n )\n endif()\n else()\n if (\"${Z3_VERSION_STRING}\" VERSION_LESS ${MINIMUM_Z3_VERSION})\n message(\n FATAL_ERROR\n \"Solidity requires Z3 ${MINIMUM_Z3_VERSION} or newer.\"\n )\n endif()\n endif()\n else()\n message(FATAL_ERROR \"Solidity requires Z3 for emscripten build.\")\n endif()\nendif()\n\nadd_subdirectory(libsolutil)\nadd_subdirectory(liblangutil)\nadd_subdirectory(libsmtutil)\nadd_subdirectory(libevmasm)\nadd_subdirectory(libyul)\nadd_subdirectory(libsolidity)\nadd_subdirectory(libsolc)\nadd_subdirectory(libstdlib)\n\nif (NOT ONLY_BUILD_SOLIDITY_LIBRARIES)\n\tadd_subdirectory(tools)\n\n\tif (NOT EMSCRIPTEN)\n\t\tadd_subdirectory(solc)\n\tendif()\n\n\tif (TESTS AND NOT EMSCRIPTEN)\n\t\tadd_subdirectory(test)\n\tendif()\nendif()\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, we as\ncontributors and maintainers pledge to make participation in our project and\nour community a harassment-free experience for everyone, regardless of age, body\nsize, disability, ethnicity, sex characteristics, gender identity and expression,\nlevel of experience, education, socioeconomic status, nationality, personal\nappearance, race, religion, or sexual identity and orientation.\n\n## Our Standards\n\nExamples of behavior that contributes to creating a positive environment\ninclude:\n\n* Using welcoming and inclusive language\n* Being respectful of differing viewpoints and experiences\n* Gracefully accepting constructive criticism\n* Focusing on what is best for the community\n* Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n* The use of sexualized language or imagery and unwelcome sexual attention or\n advances\n* Trolling, insulting/derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or electronic\n address, without explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Our Responsibilities\n\nProject maintainers are responsible for clarifying the standards of acceptable\nbehavior and are expected to take appropriate and fair corrective action in\nresponse to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit, or\nreject comments, commits, code, wiki edits, issues, and other contributions\nthat are not aligned to this Code of Conduct, or to ban temporarily or\npermanently any contributor for other behaviors that they deem inappropriate,\nthreatening, offensive, or harmful.\n\n## Scope\n\nThis Code of Conduct applies both within project spaces and in public spaces\nwhen an individual is representing the project or its community. Examples of\nrepresenting a project or community include using an official project e-mail\naddress, posting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event. Representation of a project may be\nfurther defined and clarified by project maintainers.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported by contacting the project team at solidity@ethereum.org.\nTo report an issue involving the Solidity team please email José Pedro Cabrita at zepedro@ethereum.org.\nAll complaints will be reviewed and investigated and will result in a response that\nis deemed necessary and appropriate to the circumstances. The project team is\nobligated to maintain confidentiality with regard to the reporter of an incident.\nFurther details of specific enforcement policies may be posted separately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in good\nfaith may face temporary or permanent repercussions as determined by other\nmembers of the project's leadership.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,\navailable at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html\n\n[homepage]: https://www.contributor-covenant.org\n" }, { "path": "CODING_STYLE.md", "content": "## 0. Formatting\n\n**GOLDEN RULE**: Follow the style of the existing code when you make changes.\n\n1. Use tabs for leading indentation:\n - tab stops are every 4 characters (only relevant for line length).\n - one indentation level -> exactly one byte (i.e. a tab character) in the source file.\n2. Line widths:\n - Lines should be at most 99 characters wide to make diff views readable and reduce merge conflicts.\n - Lines of comments should be formatted according to ease of viewing, but simplicity is to be preferred over beauty.\n3. Single-statement blocks should not have braces, unless required for clarity.\n4. Never place condition bodies on same line as condition.\n5. Space between keyword and opening parenthesis, but not following opening parenthesis or before final parenthesis.\n6. No spaces for unary operators, `->` or `.`.\n7. No space before `:` but one after it, except in the ternary operator: one on both sides.\n8. Add spaces around all other operators.\n9. Braces, when used, always have their own lines and are at same indentation level as \"parent\" scope.\n10. If lines are broken, a list of elements enclosed with parentheses (of any kind) and separated by a separator (of any kind) are formatted such that there is exactly one element per line, followed by the separator, the opening parenthesis is on the first line, followed by a line break and the closing parenthesis is on a line of its own unindented). See example below.\n\nYes:\n```cpp\nif (a == b[i])\n printf(\"Hello\\n\"); // NOTE spaces used instead of tab here for clarity - first byte should be '\\t'.\nfoo->bar(\n someLongVariableName,\n anotherLongVariableName,\n anotherLongVariableName,\n anotherLongVariableName,\n anotherLongVariableName\n);\ncout <<\n \"some very long string that contains completely irrelevant \" <<\n \"text that talks about this and that and contains the words \" <<\n \"\\\"lorem\\\" and \\\"ipsum\\\"\" <<\n endl;\n```\n\nNo:\n```cpp\nif( a==b[ i ] ) { printf (\"Hello\\n\"); }\nfoo->bar(someLongVariableName,\n anotherLongVariableName,\n anotherLongVariableName,\n anotherLongVariableName,\n anotherLongVariableName);\ncout << \"some very long string that contains completely irrelevant text that talks about this and that and contains the words \\\"lorem\\\" and \\\"ipsum\\\"\" << endl;\n```\n\nTo set indentation and tab width settings uniformly, the repository contains an [EditorConfig](https://editorconfig.org/) [`.editorconfig`](https://github.com/argotorg/solidity/blob/develop/.editorconfig) file, which describes some of the styles used and which is recognized by many IDE's and editors.\n\n## 1. Namespaces\n\n1. No `using namespace` declarations in header files.\n2. `using namespace solidity;` and other project local namespaces is fine in cpp files, and generally encouraged.\n3. Avoid `using namespace` at file level for third party libraries, such as boost, ranges, etc.\n4. All symbols should be declared in a namespace except for final applications.\n5. Use anonymous namespaces for helpers whose scope is a cpp file only.\n6. Preprocessor symbols should be prefixed with the namespace in all-caps and an underscore.\n\nOnly in the header:\n```cpp\n#include \nnamespace myNamespace\n{\nstd::tuple meanAndSigma(std::vector const& _v);\n}\n```\n\n## 2. Preprocessor\n\n1. File comment is always at top, and includes:\n - Copyright\n - License (e.g. see COPYING)\n2. Never use `#ifdef`/`#define`/`#endif` file guards. Prefer `#pragma` once as first line below file comment.\n3. Prefer static constexpr variables to value macros.\n4. Prefer inline constexpr functions to function macros.\n5. Split complex macro on multiple lines with `\\`.\n\n## 3. Capitalization\n\n**GOLDEN RULE**: Preprocessor: `ALL_CAPS`; C++: `camelCase`.\n\n1. Use camelCase for splitting words in names, except where obviously extending STL/boost functionality in which case follow those naming conventions.\n2. The following entities' first alpha is upper case:\n - Type names\n - Template parameters\n - Enum members\n - static const variables that form an external API.\n3. All preprocessor symbols (macros, macro arguments) in full uppercase with underscore word separation.\n\nAll other entities' first alpha is lower case.\n\n## 4. Variable prefixes\n\n1. Leading underscore \"_\" to parameter names:\n - Exception: \"o_parameterName\" when it is used exclusively for output. See 6(f).\n - Exception: \"io_parameterName\" when it is used for both input and output. See 6(f).\n2. Leading \"g_\" to global (non-const) variables.\n3. Leading \"s_\" to static (non-const, non-global) variables.\n\n## 5. Assertions\n\nUse `solAssert` and `solUnimplementedAssert` generously to check assumptions that span across different parts of the code base, for example before dereferencing a pointer.\n\n## 6. Declarations\n\n1. {Typename} + {qualifiers} + {name}.\n2. Only one per line.\n3. Associate */& with type, not variable (at ends with parser, but more readable, and safe if in conjunction with (b)).\n4. Favour declarations close to use; do not habitually declare at top of scope ala C.\n5. 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.\n6. If a function returns multiple values, use std::tuple (std::pair acceptable) or better introduce a struct type. Do not use */& arguments.\n7. 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.\n8. Never use a macro where adequate non-preprocessor C++ can be written.\n9. Only use `auto` if the type is very long and rather irrelevant.\n10. Do not pass bools: prefer enumerations instead.\n11. Prefer enum class to straight enum.\n12. Always initialize POD variables, even if their value is overwritten later.\n\nYes:\n```cpp\nenum class Accuracy\n{\n\tApproximate,\n\tExact\n};\nstruct MeanSigma\n{\n\tfloat mean = 0.0f;\n\tfloat standardDeviation = 1.0f;\n};\ndouble const d = 0;\nint i = 0;\nint j = 0;\nchar* s = nullptr;\nMeanAndSigma ms meanAndSigma(std::vector const& _v, Accuracy _a);\nDerived* x = dynamic_cast(base);\nfor (auto i = x->begin(); i != x->end(); ++i) {}\n```\n\nNo:\n```cpp\nconst double d = 0;\nint i, j;\nchar *s;\nfloat meanAndSigma(std::vector _v, float* _sigma, bool _approximate);\nDerived* x(dynamic_cast(base));\nfor (map::iterator i = l.begin(); i != l.end(); ++l) {}\n```\n\n## 7. Structs & classes\n\n1. Structs to be used when all members public and no virtual functions:\n - In this case, members should be named naturally and not prefixed with `m_`.\n2. Classes to be used in all other circumstances.\n\n## 8. Members\n\n1. One member per line only.\n2. Private, non-static, non-const fields prefixed with `m_`.\n3. Avoid public fields, except in structs.\n4. Use override, final and const as much as possible.\n5. No implementations with the class declaration, except:\n - template or force-inline method (though prefer implementation at bottom of header file).\n - one-line implementation (in which case include it in same line as declaration).\n6. For a property `foo`\n - Member: `m_foo`\n - Getter: `foo()` [ also: for booleans, `isFoo()` ]\n - Setter: `setFoo()`\n\n## 9. Naming\n\n1. Avoid unpronounceable names.\n2. Names should be shortened only if they are extremely common, but shortening should be generally avoided\n3. Avoid prefixes of initials (e.g. do not use `IMyInterface`, `CMyImplementation`)\n4. Find short, memorable & (at least semi-) descriptive names for commonly used classes or name-fragments:\n - A dictionary and thesaurus are your friends;\n - Spell correctly;\n - Think carefully about the class's purpose;\n - Imagine it as an isolated component to try to decontextualise it when considering its name;\n - Don't be trapped into naming it (purely) in terms of its implementation.\n\n## 10. Type definitions\n\n1. Prefer `using` to `typedef`. e.g. `using ints = std::vector;` rather than typedef `std::vector ints;`\n2. Generally avoid shortening a standard form that already includes all important information:\n - e.g. stick to `shared_ptr` rather than shortening to `ptr`.\n3. Where there are exceptions to this (due to excessive use and clear meaning), note the change prominently and use it consistently:\n - e.g. `using Guard = std::lock_guard;` ///< Guard is used throughout the codebase since it is clear in meaning and used commonly.\n4. In general expressions should be roughly as important/semantically meaningful as the space they occupy.\n5. Avoid introducing aliases for types unless they are very complicated. Consider the number of items a brain can keep track of at the same time.\n\n## 11. Commenting\n\n1. Comments should be doxygen-compilable, using @notation rather than \\notation.\n2. Document the interface, not the implementation:\n - Documentation should be able to remain completely unchanged, even if the method is reimplemented;\n - Comment in terms of the method properties and intended alteration to class state (or what aspects of the state it reports);\n - Be careful to scrutinise documentation that extends only to intended purpose and usage;\n - Reject documentation that is simply an English transaction of the implementation.\n3. Avoid in-code comments. Instead, try to extract blocks of functionality into functions. This often already eliminates the need for an in-code comment.\n\n## 12. Include Headers\n\n1. Includes should go in increasing order of generality (`libsolidity` -> `libevmasm` -> `libsolutil` -> `boost` -> `STL`).\n2. The corresponding `.h` file should be the first include in the respective `.cpp` file.\n3. Insert empty lines between blocks of include files.\n\nExample:\n```cpp\n#include \n\n#include \n#include \n#include \n#include \n\n#include \n\n#include \n#include \n\n#include \n#include \n\n#include \n#include \n```\n\nSee [this issue](https://stackoverflow.com/questions/614302/c-header-order/614333#614333 \"C header order\") for the reason: this makes it easier to find missing includes in header files.\n\n## 13. Recommended reading\n\n- Herb Sutter and Bjarne Stroustrup:\n - [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md)\n\n- Herb Sutter and Andrei Alexandrescu:\n - \"C++ Coding Standards: 101 Rules, Guidelines, and Best Practices\"\n\n- Scott Meyers:\n - \"Effective C++: 55 Specific Ways to Improve Your Programs and Designs (3rd Edition)\"\n - \"More Effective C++: 35 New Ways to Improve Your Programs and Designs\"\n - \"Effective Modern C++: 42 Specific Ways to Improve Your Use of C++11 and C++14\"\n" }, { "path": "CONTRIBUTING.md", "content": "# Contribution Guidelines\n\nPlease see our contribution guidelines in [the Solidity documentation](https://docs.soliditylang.org/en/latest/contributing.html).\n\nThank you for your help!\n" }, { "path": "Changelog.md", "content": "### 0.8.35 (unreleased)\n\nLanguage Features:\n* General: Add a builtin that computes the base slot of a storage namespace using the `erc7201` formula from ERC-7201.\n\nCompiler Features:\n* Commandline Interface: Disallow selecting the deprecated assembly input mode that was only accessible via `--assemble` instead of treating it as equivalent to `--strict-assembly`.\n* Commandline Interface: Introduce `--experimental` flag required for enabling the experimental mode.\n* General: Introduce the SSA CFG codegen (experimental).\n* General: Restrict the existing experimental features (`generic-solidity`, `lsp`, `ethdebug`, `eof`, `evm`, `ast-import`, `evmasm-import`, `ir-ast`, `ssa-cfg`) to experimental mode.\n* Metadata: Store the state of the experimental mode in JSON and CBOR metadata. In CBOR this broadens the meaning of the existing `experimental` field, which used to indicate only the presence of certain experimental pragmas in the source.\n* Standard JSON Interface: Introduce `settings.experimental` setting required for enabling the experimental mode.\n* Yul Optimizer: Improve performance of control flow side effects collector and function references resolver.\n\nBugfixes:\n* Yul: Fix incorrect serialization of Yul object names containing double quotes and escape sequences, producing output that could not be parsed as valid Yul.\n* Yul EVM Code Transform: Improve stack shuffler performance by fixing a BFS deduplication issue.\n\n\n### 0.8.34 (2026-02-18)\n\nImportant Bugfixes:\n* Yul IR Code Generation: Fix a bug that could result in clearing a storage variable instead of a transient storage variable at the same position in the layout (and vice-versa).\n\n\nCompiler Features:\n* Yul Optimizer: Remove redundant prerequisite steps from the default optimizer sequence.\n\n\n### 0.8.33 (2025-12-18)\n\nBugfixes:\n* TypeChecker: Fix internal error when accessing getters of constant variables.\n\n\n### 0.8.32 (2025-12-18)\n\nImportant Bugfixes:\n* Code Generator: Fix a bug in clearing/copying of arrays that straddle the end of storage, potentially resulting in assignment/initialization/`delete`/`push()`/`pop()` skipping some or all of the intended storage writes.\n\n\nBugfixes:\n* Codegen: Fix internal compiler error when emitting events via module member access.\n* TypeChecker: Fix error and event selectors not being considered compile-time constant.\n* TypeChecker: Fix `string.concat` and `bytes.concat` with constant arguments not being considered compile-time constant.\n\n\n### 0.8.31 (2025-12-03)\n\nLanguage Features:\n* Custom Storage Layout: Allow using `constant` state variables in the base slot expression.\n* DocString Parser: Warn about deprecation of inline assembly special comment `memory-safe-assembly`.\n* Syntax Checker: Warn about deprecation of ABI coder v1.\n* Syntax Checker: Warn about deprecation of virtual modifiers.\n* Type Checker: Warn about deprecation of `send` and `transfer` functions on instances of `address`.\n* Type Checker: Warn about deprecation of comparisons between variables of contract types.\n* Yul: Introduce builtin `clz(x)` for counting the number of leading zero bits in a 256-bit word.\n\n\nCompiler Features:\n* ethdebug: Experimental support for instructions and source locations under EOF.\n* EVM: Set default EVM Version to `osaka`.\n\n\nBugfixes:\n* Assembler: Fix not using a fixed-width type for IDs being assigned to subassemblies nested more than one level away, resulting in inconsistent `--asm-json` output between target architectures.\n* Yul Optimizer: Fix edge case in which invalid Yul code is produced by ExpressionSimplifier due to expressions being substituted that contain out-of-scope variables.\n\n\nBuild System:\n* Enable Linux arm64 binaries for testing and releases.\n* Ubuntu PPA Packages: Discontinue the PPA as a binary distribution channel.\n* Update minimum version requirements of Boost to 1.83.0 for non-windows builds and of GCC and Clang to 13.3 and 18.1.3, respectively. Fixes infinite recursion on `boost::rational` comparison affecting compiler binaries built with GCC<14.0 and Boost<1.75.\n\n\n### 0.8.30 (2025-05-07)\n\nCompiler Features:\n* EVM: Set default EVM Version to `prague`.\n* NatSpec: Capture Natspec documentation of `enum` values in the AST.\n\n\nBugfixes:\n* SMTChecker: Do not consider loop conditions as constant-condition verification target as this could cause incorrect reports and internal compiler errors.\n* SMTChecker: Fix incorrect analysis when only a subset of contracts is selected with `--model-checker-contracts`.\n* SMTChecker: Fix internal compiler error when string literal is used to initialize user-defined type based on fixed bytes.\n\n\n### 0.8.29 (2025-03-12)\n\nLanguage Features:\n * Allow relocating contract storage to an arbitrary location.\n\n\nCompiler Features:\n * Error Reporting: Errors reported during code generation now point at the location of the contract when more fine-grained location is not available.\n * ethdebug: Experimental support for instructions and source locations.\n * EVM: Support for the EVM version \"Osaka\".\n * EVM Assembly Import: Allow enabling opcode-based optimizer.\n * General: The experimental EOF backend implements a subset of EOF sufficient to compile arbitrary high-level Solidity syntax via IR with optimization enabled.\n * SMTChecker: Support ``block.blobbasefee`` and ``blobhash``.\n * SMTChecker: The option ``--model-checker-print-query`` no longer requires ``--model-checker-solvers smtlib2``.\n * SMTChecker: Z3 is now a runtime dependency, not a build dependency (except for emscripten build).\n * Yul Parser: Make name clash with a builtin a non-fatal error.\n\n\nBugfixes:\n * Commandline Interface: Report StackTooDeep errors in compiler mode as proper errors instead of printing diagnostic information meant for internal compiler errors.\n * Error Reporting: Fix error locations not being shown for source files with empty names.\n * General: Fix internal compiler error when requesting IR AST outputs for interfaces and abstract contracts.\n * Metadata: Fix custom cleanup sequence missing from metadata when other optimizer settings have default values.\n * SMTChecker: Fix internal compiler error when analyzing overflowing expressions or bitwise negation of unsigned types involving constants.\n * SMTChecker: Fix reporting on targets that are safe in the context of one contract but unsafe in the context of another contract.\n * SMTChecker: Fix SMT logic error when analyzing cross-contract getter call with BMC.\n * SMTChecker: Fix SMT logic error when contract deployment involves string literal to fixed bytes conversion.\n * SMTChecker: Fix SMT logic error when external call has extra effectless parentheses.\n * SMTChecker: Fix SMT logic error when initializing a fixed-sized-bytes array using string literals.\n * SMTChecker: Fix SMT logic error when translating invariants involving array store and select operations.\n * SMTChecker: Fix wrong encoding of string literals as arguments of ``ecrecover`` precompile.\n * Standard JSON Interface: Fix ``generatedSources`` and ``sourceMap`` being generated internally even when not requested.\n * TypeChecker: Fix spurious compilation errors due to incorrect computation of contract storage size which erroneously included transient storage variables.\n * Yul: Fix internal compiler error when a code generation error should be reported instead.\n * Yul Optimizer: Fix failing debug assertion due to dereferencing of an empty ``optional`` value.\n\n\nBuild system:\n * Linux release builds are fully static again and no longer depend on ``glibc``.\n * Switch from C++17 to C++20 as the target standard.\n\n\nSolc-Js:\n * The wrapper now requires at least nodejs v12.\n\n### 0.8.28 (2024-10-09)\n\nLanguage Features:\n * Transient storage state variables of value types are now fully supported.\n\n\nCompiler Features:\n * General: Generate JSON representations of Yul ASTs only on demand to reduce memory usage.\n * Standard JSON Interface: Bytecode or IR can now be requested for a subset of all contracts without triggering unnecessary code generation for other contracts.\n\n\nBugfixes:\n * SMTChecker: Fix SMT logic error when assigning to an array of addresses.\n * Yul AST: Fix shifted native source locations when debug info selection included code snippets.\n\n\nBuild system:\n* Removed ``USE_LD_GOLD`` option and default to use the compiler default linker. For custom linkers, ``CMAKE_CXX_FLAGS`` can be used.\n\n\n### 0.8.27 (2024-09-04)\n\nLanguage Features:\n * Accept declarations of state variables with ``transient`` data location (parser support only, no code generation yet).\n * Make ``require(bool, Error)`` available when using the legacy pipeline.\n * Yul: Parsing rules for source location comments have been relaxed: Whitespace between the location components as well as single-quoted code snippets are now allowed.\n\n\nCompiler Features:\n * Commandline Interface: Add ``--transient-storage-layout`` output.\n * Commandline Interface: Allow the use of ``--asm-json`` output option in assembler mode to export EVM assembly of the contracts in JSON format.\n * Commandline Interface: Do not perform IR optimization when only unoptimized IR is requested.\n * Constant Optimizer: Uses ``PUSH0`` if supported by the selected evm version.\n * Error Reporting: Unimplemented features are now properly reported as errors instead of being handled as if they were bugs.\n * EVM: Support for the EVM version \"Prague\".\n * Peephole Optimizer: ``PUSH0``, when supported, is duplicated explicitly instead of using ``DUP1``.\n * Peephole Optimizer: Remove identical code snippets that terminate the control flow if they occur one after another.\n * SMTChecker: Add CHC engine check for underflow and overflow in unary minus operation.\n * SMTChecker: Replace CVC4 as a possible BMC backend with cvc5.\n * Standard JSON Interface: Add ``transientStorageLayout`` output.\n * Standard JSON Interface: Do not perform IR optimization when only unoptimized IR is requested.\n * Yul: Drop the deprecated typed Yul dialect that was only accessible via ``--yul`` in the CLI.\n * Yul: The presence of types in untyped Yul dialects is now a parser error.\n * Yul Optimizer: Caching of optimized IR to speed up optimization of contracts with bytecode dependencies.\n * Yul Optimizer: The optimizer now treats some previously unrecognized identical literals as identical.\n\n\nBugfixes:\n * Assembler: Fix ICE caused by imprecise calculation of required size of tags in bytecode when code size is above 255.\n * Parser: Fix spuriously emitted parser error for unary plus operations when used as binary operator in some cases.\n * SMTChecker: Fix error that reports invalid number of verified checks for BMC and CHC engines.\n * SMTChecker: Fix formatting of unary minus expressions in invariants.\n * SMTChecker: Fix internal compiler error when reporting proved targets for BMC engine.\n * SMTChecker: Fix SMT logic error when assigning to an array of contracts or functions.\n * Standard JSON Interface: For Yul input, properly produce output artifacts in case of warnings.\n * TypeChecker: Fix segfault when assigning nested tuple to tuple.\n * Yul IR Code Generation: Deterministic order of Yul subobjects.\n * Yul Optimizer: Fix Yul source locations always referring to unoptimized source, even in optimized outputs.\n * Yul Optimizer: Fix warnings being generated twice when there are no errors.\n * Yul Optimizer: Name simplification could lead to forbidden identifiers with a leading and/or trailing dot, e.g., ``x._`` would get simplified into ``x.``.\n * Yul Parser: Fix segfault when parsing very long location comments.\n\nBuild System:\n * Change build system to use git submodules for some dependencies (nlohmann-json, fmtlib & range-v3).\n\n### 0.8.26 (2024-05-21)\n\nLanguage Features:\n * Introduce a new overload ``require(bool, Error)`` that allows usage of ``require`` functions with custom errors. This feature is available in the ``via-ir`` pipeline only.\n\n\nCompiler Features:\n * SMTChecker: Create balance check verification target for CHC engine.\n * Yul IR Code Generation: Cheaper code for reverting with errors of a small static encoding size.\n * Yul Optimizer: New, faster default optimizer step sequence.\n\n\nBugfixes:\n * Commandline Interface: Fix ICE when the optimizer is disabled and an empty/blank string is used for ``--yul-optimizations`` sequence.\n * SMTChecker: Fix false positive when comparing hashes of same array or string literals.\n * SMTChecker: Fix internal error on mapping access caused by too strong requirements on sort compatibility of the index and mapping domain.\n * SMTChecker: Fix internal error when using an empty tuple in a conditional operator.\n * SMTChecker: Fix internal error when using bitwise operators with an array element as argument.\n * Standard JSON Interface: Fix ICE when the optimizer is disabled and an empty/blank string is used for ``optimizerSteps`` sequence.\n * StaticAnalyzer: Only raise a compile time error for division and modulo by zero when it's between literals.\n * TypeChecker: Fix compiler crash when the left-hand side of an assignment was a parenthesized non-tuple expression of a tuple type.\n * Yul Optimizer: Fix optimizer executing each repeating part of the step sequence at least twice, even if the code size already became stable after the first iteration.\n * Yul Optimizer: Fix the order of assignments generated by ``SSATransform`` being dependent on AST IDs, sometimes resulting in different (but equivalent) bytecode when unrelated files were added to the compilation pipeline.\n\n\nBuild System:\n* Replace internal JSON library jsoncpp with nlohmann::json.\n\n\n### 0.8.25 (2024-03-14)\n\nCompiler Features:\n * Code Generator: Use ``MCOPY`` instead of ``MLOAD``/``MSTORE`` loop when copying byte arrays.\n * EVM: Set default EVM version to ``cancun``.\n * Yul Analyzer: Emit transient storage warning only for the first occurrence of ``tstore``.\n\n\nBugfixes:\n * Assembler: Prevent incorrect calculation of tag sizes.\n * Commandline Interface: Do not run IR pipeline when ``--via-ir`` is used but no output that depends on the IR is requested.\n * EVM Assembly Import: Fix handling of missing source locations during import.\n * SMTChecker: Ensure query is properly flushed to a file before calling solver when using SMT-LIB interface.\n * SMTChecker: Fix internal error caused by not respecting the sign of an integer type when constructing zero-value SMT expressions.\n * SMTChecker: Run Eldarica only when explicitly requested with `--model-checker-solvers eld`, even when it is present on the system.\n\n### 0.8.24 (2024-01-25)\n\nLanguage Features:\n * Introduce global ``block.blobbasefee`` for retrieving the blob base fee of the current block.\n * Introduce global function ``blobhash(uint)`` for retrieving versioned hashes of blobs, akin to the homonymous Yul builtin.\n * Yul: Introduce builtin ``blobbasefee()`` for retrieving the blob base fee of the current block.\n * Yul: Introduce builtin ``blobhash()`` for retrieving versioned hashes of blobs associated with the transaction.\n * Yul: Introduce builtin ``mcopy()`` for cheaply copying data between memory areas.\n * Yul: Introduce builtins ``tload()`` and ``tstore()`` for transient storage access.\n\n\nCompiler Features:\n * EVM: Support for the EVM Version \"Cancun\".\n * SMTChecker: Support `bytes.concat` except when string literals are passed as arguments.\n * SMTChecker: Print a message that function parameter name was used instead of a concrete value in a counterexample when the concrete value found by the solver is too long to print.\n * Standard JSON Interface: Add experimental support to import EVM assembly in the format used by ``--asm-json``.\n * TypeChecker: Comparison of internal function pointers now yields a warning, as it can produce unexpected results with the legacy pipeline enabled.\n\n\nBugfixes:\n * AST import: Fix bug when importing inline assembly with empty ``let`` variable declaration.\n\n\n### 0.8.23 (2023-11-08)\n\nImportant Bugfixes:\n * Optimizer: Fix block deduplicator bug which led to blocks which are identical apart from the contents of ``verbatim`` instructions to be treated as equivalent and thus collapsed into a single one.\n\n\nCompiler Features:\n * Commandline Interface: An empty ``--yul-optimizations`` sequence can now be always provided.\n * Standard JSON Interface: An empty ``optimizerSteps`` sequence can now always be provided.\n\n\n### 0.8.22 (2023-10-25)\n\nLanguage Features:\n * Allow defining events at file level.\n\n\nCompiler Features:\n * Code Generator: Remove redundant overflow checks of certain ``for`` loops when the counter variable cannot overflow.\n * Commandline Interface: Add ``--no-import-callback`` option that prevents the compiler from loading source files not given explicitly on the CLI or in Standard JSON input.\n * Commandline Interface: Add an experimental ``--import-asm-json`` option that can import EVM assembly in the format used by ``--asm-json``.\n * Commandline Interface: Use proper severity and coloring also for error messages produced outside of the compilation pipeline.\n * EVM: Deprecate support for \"homestead\", \"tangerineWhistle\", \"spuriousDragon\" and \"byzantium\" EVM versions.\n * Parser: Remove the experimental error recovery mode (``--error-recovery`` / ``settings.parserErrorRecovery``).\n * SMTChecker: Support user-defined operators.\n * Yul Optimizer: If ``PUSH0`` is supported, favor zero literals over storing zero values in variables.\n * Yul Optimizer: Run the ``Rematerializer`` and ``UnusedPruner`` steps at the end of the default clean-up sequence.\n\n\nBugfixes:\n * AST: Fix wrong initial ID for Yul nodes in the AST.\n * 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.\n * NatSpec: Fix internal error when requesting userdoc or devdoc for a contract that emits an event defined in a foreign contract or interface.\n * SMTChecker: Fix encoding error that causes loops to unroll after completion.\n * SMTChecker: Fix inconsistency on constant condition checks when ``while`` or ``for`` loops are unrolled before the condition check.\n * Yul Optimizer: Fix replacement decisions during CSE being affected by Yul variable names generated by the compiler, resulting in different (but equivalent) bytecode in some situations.\n\n\n### 0.8.21 (2023-07-19)\n\nImportant Bugfixes:\n * Code Generator: Always generate code for the expression in ``.selector`` in the legacy code generation pipeline.\n * 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``)).\n\n\nLanguage Features:\n * Allow qualified access to events from other contracts.\n * 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.\n\n\nCompiler Features:\n * Commandline Interface: Add ``--ast-compact-json`` output in assembler mode.\n * 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.\n * 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.\n * EWasm: Remove EWasm backend.\n * 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.\n * 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.\n * Standard JSON Interface: Add ``ast`` file-level output for Yul input.\n * Standard JSON Interface: Add ``irAst`` and ``irOptimizedAst`` contract-level outputs for Solidity input, providing AST in compact JSON format for IR and optimized IR.\n * Yul Optimizer: Remove experimental ``ReasoningBasedSimplifier`` optimization step.\n * Yul Optimizer: Stack-to-memory mover is now enabled by default whenever possible for via IR code generation and pure Yul compilation.\n\n\nBugfixes:\n * 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.\n * 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).\n * Commandline Interface: Fix internal error when using ``--stop-after parsing`` and requesting some of the outputs that require full analysis or compilation.\n * Commandline Interface: It is no longer possible to specify both ``--optimize-yul`` and ``--no-optimize-yul`` at the same time.\n * SMTChecker: Fix encoding of side-effects inside ``if`` and ``ternary conditional``statements in the BMC engine.\n * SMTChecker: Fix false negative when a verification target can be violated only by trusted external call from another public function.\n * SMTChecker: Fix generation of invalid SMT-LIB2 scripts in BMC engine with trusted mode for external calls when CHC engine times out.\n * SMTChecker: Fix internal error caused by incorrectly classifying external function call using function pointer as a public getter.\n * SMTChecker: Fix internal error caused by using external identifier to encode member access to functions that take an internal function as a parameter.\n * Standard JSON Interface: Fix an incomplete AST being returned when analysis is interrupted by certain kinds of fatal errors.\n * Type Checker: Disallow using certain unassignable function types in complex expressions.\n * Type Checker: Function declaration types referring to different declarations are no longer convertible to each other.\n * 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.\n * Yul Optimizer: Fix ``FullInliner`` step not ignoring code that is not in expression-split form.\n * Yul Optimizer: Fix optimized IR being unnecessarily passed through the Yul optimizer again before bytecode generation.\n\n\nAST Changes:\n * AST: Add the ``experimentalSolidity`` field to the ``SourceUnit`` nodes, which indicate whether the experimental parsing mode has been enabled via ``pragma experimental solidity``.\n\n\n### 0.8.20 (2023-05-10)\n\nCompiler Features:\n * Assembler: Use ``push0`` for placing ``0`` on the stack for EVM versions starting from \"Shanghai\". This decreases the deployment and runtime costs.\n * EVM: Set default EVM version to \"Shanghai\".\n * EVM: Support for the EVM Version \"Shanghai\".\n * NatSpec: Add support for NatSpec documentation in ``enum`` definitions.\n * NatSpec: Add support for NatSpec documentation in ``struct`` definitions.\n * NatSpec: Include NatSpec from events that are emitted by a contract but defined outside of it in userdoc and devdoc output.\n * 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.\n * 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).\n * 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.\n * 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.\n * 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.\n * Standard JSON Interface: Add experimental support for importing ASTs via Standard JSON.\n * 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.\n\n\nBugfixes:\n * ABI: Include events in the ABI that are emitted by a contract but defined outside of it.\n * Immutables: Disallow initialization of immutables in try/catch statements.\n * SMTChecker: Fix false positives in ternary operators that contain verification targets in its branches, directly or indirectly.\n\n\nAST Changes:\n * 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.\n * 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.\n\n\n### 0.8.19 (2023-02-22)\n\nLanguage Features:\n * Allow defining custom operators for user-defined value types via ``using {f as +} for T global`` syntax.\n\n\nCompiler Features:\n * 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\"``.\n\n\nBugfixes:\n * Assembler: Avoid duplicating subassembly bytecode where possible.\n * Code Generator: Avoid including references to the deployed label of referenced functions if they are called right away.\n * ContractLevelChecker: Properly distinguish the case of missing base constructor arguments from having an unimplemented base function.\n * SMTChecker: Fix internal error caused by unhandled ``z3`` expressions that come from the solver when bitwise operators are used.\n * SMTChecker: Fix internal error when using the custom NatSpec annotation to abstract free functions.\n * TypeChecker: Also allow external library functions in ``using for``.\n\n\nAST Changes:\n * 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.\n\n\n### 0.8.18 (2023-02-01)\n\nLanguage Features:\n * Allow named parameters in mapping types.\n\n\nCompiler Features:\n * Commandline Interface: Add ``--no-cbor-metadata`` that skips CBOR metadata from getting appended at the end of the bytecode.\n * Commandline Interface: Return exit code ``2`` on uncaught exceptions.\n * 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).\n * EVM: Introduce ``block.prevrandao`` in Solidity and ``prevrandao()`` in inline assembly for EVM versions >= paris.\n * EVM: Set the default EVM version to \"Paris\".\n * EVM: Support for the EVM version \"Paris\".\n * Language Server: Add basic document hover support.\n * Natspec: Add event Natspec inheritance for devdoc.\n * Optimizer: Added optimization rule ``and(shl(X, Y), shl(X, Z)) => shl(X, and(Y, Z))``.\n * Parser: More detailed error messages about invalid version pragmas.\n * SMTChecker: Make ``z3`` the default solver for the BMC and CHC engines instead of all solvers.\n * 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.\n * Solidity Upgrade Tool: Remove ``solidity-upgrade`` tool.\n * Standard JSON: Add a boolean field ``settings.metadata.appendCBOR`` that skips CBOR metadata from getting appended at the end of the bytecode.\n * TypeChecker: Warn when using deprecated builtin ``selfdestruct``.\n * 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.\n * Yul Optimizer: Allow replacing the previously hard-coded cleanup sequence by specifying custom steps after a colon delimiter (``:``) in the sequence string.\n * Yul Optimizer: Eliminate ``keccak256`` calls if the value was already calculated by a previous call and can be reused.\n\n\nBugfixes:\n * Parser: Disallow several ``indexed`` attributes for the same event parameter.\n * Parser: Disallow usage of the ``indexed`` attribute for modifier parameters.\n * SMTChecker: Fix display error for negative integers that are one more than powers of two.\n * SMTChecker: Fix internal error on chain assignments using static fully specified state variables.\n * SMTChecker: Fix internal error on multiple wrong SMTChecker natspec entries.\n * SMTChecker: Fix internal error when a public library function is called internally.\n * SMTChecker: Fix internal error when deleting struct member of function type.\n * SMTChecker: Fix internal error when using user-defined types as mapping indices or struct members.\n * SMTChecker: Improved readability for large integers that are powers of two or almost powers of two in error messages.\n * TypeChecker: Fix bug where private library functions could be attached with ``using for`` outside of their declaration scope.\n * Yul Optimizer: Hash hex and decimal literals according to their value instead of their representation, improving the detection of equivalent functions.\n\n\n### 0.8.17 (2022-09-08)\n\nImportant Bugfixes:\n * Yul Optimizer: Prevent the incorrect removal of storage writes before calls to Yul functions that conditionally terminate the external EVM call.\n\n\nCompiler Features:\n * Code Generator: More efficient overflow checks for multiplication.\n * 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).\n * Yul Optimizer: Simplify the starting offset of zero-length operations to zero.\n\n\nBugfixes:\n * Type Checker: Fix internal compiler error on tuple assignments with invalid left-hand side.\n * Yul IR Code Generation: Fix internal compiler error when accessing the ``.slot`` member of a mapping through a storage reference in inline assembly.\n\n\nBuild System:\n * Allow disabling pedantic warnings and do not treat warnings as errors during compiler build when ``-DPEDANTIC=OFF`` flag is passed to CMake.\n * Update emscripten to version 3.1.19.\n\n\n### 0.8.16 (2022-08-08)\n\nImportant Bugfixes:\n * Code Generation: Fix data corruption that affected ABI-encoding of calldata values represented by tuples: structs at any nesting level; argument lists of external functions, events and errors; return value lists of external functions. The 32 leading bytes of the first dynamically-encoded value in the tuple would get zeroed when the last component contained a statically-encoded array.\n\n\nCompiler Features:\n * Code Generator: More efficient code for checked addition and subtraction.\n * TypeChecker: Support using library constants in initializers of other constants.\n * Yul IR Code Generation: Improved copy routines for arrays with packed storage layout.\n * Yul Optimizer: Add rule to convert ``mod(add(X, Y), A)`` into ``addmod(X, Y, A)``, if ``A`` is a power of two.\n * Yul Optimizer: Add rule to convert ``mod(mul(X, Y), A)`` into ``mulmod(X, Y, A)``, if ``A`` is a power of two.\n\n\nBugfixes:\n * Commandline Interface: Disallow the following options outside of the compiler mode: ``--via-ir``,``--metadata-literal``, ``--metadata-hash``, ``--model-checker-show-unproved``, ``--model-checker-div-mod-no-slacks``, ``--model-checker-engine``, ``--model-checker-invariants``, ``--model-checker-solvers``, ``--model-checker-timeout``, ``--model-checker-contracts``, ``--model-checker-targets``.\n * Type Checker: Fix compiler crash on tuple assignments involving certain patterns with unary tuples on the left-hand side.\n * Type Checker: Fix compiler crash when ``abi.encodeCall`` received a tuple expression instead of an inline tuple.\n * Type Checker: Fix null dereference in ``abi.encodeCall`` type checking of free function.\n\n\n### 0.8.15 (2022-06-15)\n\nImportant Bugfixes:\n * Code Generation: Avoid writing dirty bytes to storage when copying ``bytes`` arrays.\n * Yul Optimizer: Keep all memory side-effects of inline assembly blocks.\n\n\nLanguage Features:\n * Add `E.selector` for a non-anonymous event `E` to access the 32-byte selector topic.\n\n\nCompiler Features:\n * Language Server: Add rudimentary support for semantic highlighting.\n * Language Server: Adds support for configuring ``include-paths`` JSON settings object that can be passed during LSP configuration stage.\n * Language Server: Always add ``{project_root}/node_modules`` to include search paths.\n * Type Checker: Warn about assignments involving multiple pushes to storage ``bytes`` that may invalidate references.\n * Yul Optimizer: Improve inlining heuristics for via IR code generation and pure Yul compilation.\n\nBugfixes:\n * ABI Encoder: When encoding an empty string coming from storage do not add a superfluous empty slot for data.\n * Common Subexpression Eliminator: Process assembly items in chunks with maximum size of 2000. It helps to avoid extremely time-consuming searches during code optimization.\n * DocString Parser: Fix ICE caused by an immutable struct with mapping.\n * Yul IR Code Generation: More robust cleanup in corner cases during memory to storage copies.\n * Yul Optimizer: Do not remove ``returndatacopy`` in cases in which it might perform out-of-bounds reads that unconditionally revert as out-of-gas. Previously, any ``returndatacopy`` that wrote to memory that was never read from was removed without accounting for the out-of-bounds condition.\n\n\n### 0.8.14 (2022-05-17)\n\nImportant Bugfixes:\n * ABI Encoder: When ABI-encoding values from calldata that contain nested arrays, correctly validate the nested array length against ``calldatasize()`` in all cases.\n * Override Checker: Allow changing data location for parameters only when overriding external functions.\n\n\nCompiler Features:\n * Assembly-Json Exporter: Include source list in `sourceList` field.\n * Commandline Interface: Option ``--pretty-json`` works also with the following options: ``--abi``, ``--asm-json``, ``--ast-compact-json``, ``--devdoc``, ``--storage-layout``, ``--userdoc``.\n * Language Server: Allow full filesystem access to language server.\n * Peephole Optimizer: Remove operations without side effects before simple terminations.\n * SMTChecker: Support ``abi.encodeCall`` taking into account the called selector.\n\n\nBugfixes:\n * Assembly-Json Exporter: Fix assembly json export to store jump types of operations in `jumpType` field instead of `value`.\n * SMTChecker: Fix ABI compatibility with z3 >=4.8.16.\n * SMTChecker: Fix bug when z3 is selected but not available at runtime.\n * Type Checker: Properly check restrictions of ``using ... global`` in conjunction with libraries.\n * TypeChecker: Convert parameters of function type to how they would be called for ``abi.encodeCall``.\n\n\n### 0.8.13 (2022-03-16)\n\nImportant Bugfixes:\n * Code Generator: Correctly encode literals used in ``abi.encodeCall`` in place of fixed bytes arguments.\n\n\nLanguage Features:\n * General: Allow annotating inline assembly as memory-safe to allow optimizations and stack limit evasion that rely on respecting Solidity's memory model.\n * General: ``using M for Type;`` is allowed at file level and ``M`` can now also be a brace-enclosed list of free functions or library functions.\n * General: ``using ... for T global;`` is allowed at file level where the user-defined type ``T`` has been defined, resulting in the effect of the statement being available everywhere ``T`` is available.\n\n\nCompiler Features:\n * Commandline Interface: Allow the use of ``--via-ir`` in place of ``--experimental-via-ir``.\n * Compilation via Yul IR is no longer marked as experimental.\n * JSON-AST: Added selector field for errors and events.\n * Language Server: Implements goto-definition.\n * Peephole Optimizer: Optimize comparisons in front of conditional jumps and conditional jumps across a single unconditional jump.\n * Yul EVM Code Transform: Avoid unnecessary ``pop``s on terminating control flow.\n * Yul IR Code Generation: When the result of an external call is statically-sized, ignore any returndata past the size expected by the compiler.\n * Yul Optimizer: Remove ``sstore`` and ``mstore`` operations that are never read from.\n\n\nBugfixes:\n * General: Fix internal error for locales with unusual capitalization rules. Locale set in the environment is now completely ignored.\n * Type Checker: Fix incorrect type checker errors when importing overloaded functions.\n * Yul IR Code Generation: Optimize embedded creation code with correct settings. This fixes potential mismatches between the constructor code of a contract compiled in isolation and the bytecode in ``type(C).creationCode``, resp. the bytecode used for ``new C(...)``.\n\n\n### 0.8.12 (2022-02-16)\n\nLanguage Features:\n * General: Add equality-comparison operators for external function types.\n * General: Support ``ContractName.functionName`` for ``abi.encodeCall``, in addition to external function pointers.\n\n\nCompiler Features:\n * Commandline Interface: Event and error signatures are also returned when using ``--hashes``.\n * Yul Optimizer: Remove ``mstore`` and ``sstore`` operations if the slot already contains the same value.\n * Yul: Emit immutable references for pure yul code when requested.\n\n\n\nBugfixes:\n * Antlr Grammar: Allow builtin names in ``yulPath`` to support ``.address`` in function pointers.\n * Code Generator: Fix internal error when accessing the members of external functions occupying more than two stack slots.\n * Code Generator: Fix internal error when doing an explicit conversion from ``string calldata`` to ``bytes``.\n * Control Flow Graph: Perform proper virtual lookup for modifiers for uninitialized variable and unreachable code analysis.\n * General: ``string.concat`` now properly takes strings as arguments and returns ``string memory``. It was accidentally introduced as a copy of ``bytes.concat`` before.\n * Immutables: Fix wrong error when the constructor of a base contract uses ``return`` and the derived contract contains immutable variables.\n * Inheritance: Consider functions in all ancestors during override analysis.\n * IR Generator: Add missing cleanup during the conversion of fixed bytes types to smaller fixed bytes types.\n * IR Generator: Add missing cleanup for indexed event arguments of value type.\n * IR Generator: Fix internal error when copying reference types in calldata and storage to struct or array members in memory.\n * IR Generator: Fix IR syntax error when copying storage arrays of structs containing functions.\n * Natspec: Fix internal error when overriding a struct getter with a Natspec-documented return value and the name in the struct is different.\n * Type Checker: Fix internal error when a constant variable declaration forward references a struct.\n * Yul EVM Code Transform: Improved stack shuffling in corner cases.\n\n\nSolc-Js:\n * The wrapper now requires at least nodejs v10.\n * The code has been ported to TypeScript.\n\n\nBuild System:\n * Emscripten builds store the embedded WebAssembly binary in LZ4 compressed format and transparently decompress on loading.\n\n\n### 0.8.11 (2021-12-20)\n\nLanguage Features:\n * General: New builtin function ``abi.encodeCall(functionPointer, (arg1, arg2, ...))`` that type-checks the arguments and returns the ABI-encoded function call data.\n\n\nCompiler Features:\n * Commandline Interface: Add ``--lsp`` option to get ``solc`` to act as a Language Server (LSP) communicating over stdio.\n\n\nBugfixes:\n * Code Generator: Fix a crash when using ``@use-src`` and compiling from Yul to ewasm.\n * SMTChecker: Fix internal error when an unsafe target is solved more than once and the counterexample messages are different.\n * SMTChecker: Fix soundness of assigned storage/memory local pointers that were not erasing enough knowledge.\n * Fix internal error when a function has a calldata struct argument with an internal type inside.\n * IR Generator: Fix IR syntax error when copying storage arrays of functions.\n\n\n### 0.8.10 (2021-11-09)\n\nLanguage Features:\n * Inline Assembly: Support ``.address`` and ``.selector`` on external function pointers to access their address and function selector.\n\n\nCompiler Features:\n * Code Generator: Skip existence check for external contract if return data is expected. In this case, the ABI decoder will revert if the contract does not exist.\n * Commandline Interface: Accept nested brackets in step sequences passed to ``--yul-optimizations``.\n * Commandline Interface: Add ``--debug-info`` option for selecting how much extra debug information should be included in the produced EVM assembly and Yul code.\n * Commandline Interface: Support ``--asm``, ``--bin``, ``--ir-optimized``, ``--ewasm`` and ``--ewasm-ir`` output selection options in assembler mode.\n * Commandline Interface: Use different colors when printing errors, warnings and infos.\n * JSON AST: Set absolute paths of imports earlier, in the ``parsing`` stage.\n * SMTChecker: Output values for ``block.*``, ``msg.*`` and ``tx.*`` variables that are present in the called functions.\n * SMTChecker: Report contract invariants and reentrancy properties. This can be enabled via the CLI option ``--model-checker-invariants`` or the Standard JSON option ``settings.modelChecker.invariants``.\n * Standard JSON: Accept nested brackets in step sequences passed to ``settings.optimizer.details.yulDetails.optimizerSteps``.\n * Standard JSON: Add ``settings.debug.debugInfo`` option for selecting how much extra debug information should be included in the produced EVM assembly and Yul code.\n * Yul EVM Code Transform: Switch to new optimized code transform when compiling via Yul with enabled optimizer.\n * Yul Optimizer: Take control-flow side-effects of user-defined functions into account in various optimizer steps.\n\n\nBugfixes:\n * Code Generator: Fix constructor source mappings for immutables.\n * Commandline Interface: Disallow ``--error-recovery`` option outside of the compiler mode.\n * Commandline Interface: Don't return zero exit code when writing linked files to disk fails.\n * Commandline Interface: Fix extra newline character being appended to sources passed through standard input, affecting their hashes.\n * Commandline Interface: Report output selection options unsupported by the selected input mode instead of ignoring them.\n * Commandline Interface: When linking only accept exact matches for library names passed to the ``--libraries`` option. Library names not prefixed with a file name used to match any library with that name.\n * SMTChecker: Fix internal error in magic type access (``block``, ``msg``, ``tx``).\n * SMTChecker: Fix internal error in the CHC engine when passing gas in the function options.\n * TypeChecker: Fix internal error when using arrays and structs with user defined value types before declaration.\n * TypeChecker: Fix internal error when using user defined value types in public library functions.\n * TypeChecker: Improved error message for constant variables with (nested) mapping types.\n * Yul Assembler: Fix internal error when function names are not unique.\n * Yul IR Generator: Do not output empty switches/if-bodies for empty contracts.\n\n\nImportant Bugfixes in Experimental Features:\n * Yul IR Generator: Changes to function return variables referenced in modifier invocation arguments were not properly forwarded if there was more than one return variable.\n\n\nBuild System:\n * Pass linker-only emscripten options only when linking.\n * Remove obsolete compatibility workaround for emscripten builds.\n * Update emscripten to version 2.0.33.\n\n\n### 0.8.9 (2021-09-29)\n\nImportant Bugfixes:\n * Immutables: Properly perform sign extension on signed immutables.\n * User Defined Value Type: Fix storage layout of user defined value types for underlying types shorter than 32 bytes.\n\n\nBugfixes:\n * AST: Export ``canonicalName`` for ``UserDefinedValueTypeDefinition`` and ``ContractDefinition``.\n\n\n\n### 0.8.8 (2021-09-27)\n\nLanguage Features:\n * Inheritance: A function that overrides only a single interface function does not require the ``override`` specifier.\n * Type System: Support ``type(E).min`` and ``type(E).max`` for enums.\n * User Defined Value Type: allows creating a zero cost abstraction over a value type with stricter type requirements.\n\n\nCompiler Features:\n * Commandline Interface: Add ``--include-path`` option for specifying extra directories that may contain importable code (e.g. packaged third-party libraries).\n * Commandline Interface: Do not implicitly run evm bytecode generation unless needed for the requested output.\n * Commandline Interface: Normalize paths specified on the command line and make them relative for files located inside base path and/or include paths.\n * Immutable variables can be read at construction time once they are initialized.\n * SMTChecker: Add constraints to better correlate ``address(this).balance`` and ``msg.value``.\n * SMTChecker: Support constants via modules.\n * SMTChecker: Support low level ``call`` as external calls to unknown code.\n * SMTChecker: Support the ``value`` option for external function calls.\n * SMTChecker: Support user defined value types.\n\n\nBugfixes:\n * Code Generator: Fix ICE on assigning to calldata structs and statically-sized calldata arrays in inline assembly.\n * Code Generator: Use stable source order for ABI functions.\n * Commandline Interface: Disallow the ``--experimental-via-ir`` option in Standard JSON, Assembler and Linker modes.\n * Commandline Interface: Fix resolution of paths whitelisted with ``--allowed-paths`` or implicitly due to base path, remappings and files being compiled. Correctly handle paths that do not match imports exactly due to being relative, non-normalized or empty.\n * Commandline Interface: Report optimizer options as invalid in Standard JSON and linker modes instead of ignoring them.\n * Name Resolver: Fix that when importing an aliased symbol using ``import {AliasedName} from \"a.sol\"`` it would use the original name of the symbol and not the aliased one.\n * Opcode Optimizer: Prevent the optimizer from running multiple times to avoid potential bytecode differences for referenced code.\n * Parser: Properly check for multiple SPDX license identifiers next to each other and validate them.\n * SMTChecker: Fix BMC's constraints regarding internal functions.\n * SMTChecker: Fix false negative caused by ``push`` on storage array references returned by internal functions.\n * SMTChecker: Fix false positive in external calls from constructors.\n * SMTChecker: Fix internal error on some multi-source uses of ``abi.*``, cryptographic functions and constants.\n * Standard JSON: Fix non-fatal errors in Yul mode being discarded if followed by a fatal error.\n * Type Checker: Correct wrong error message in inline assembly complaining about ``.slot`` or ``.offset`` not valid when actually ``.length`` was used.\n * Type Checker: Disallow modifier declarations and definitions in interfaces.\n * Yul Optimizer: Fix a crash in LoadResolver, when ``keccak256`` has particular non-identifier arguments.\n\n\n\n### 0.8.7 (2021-08-11)\n\nLanguage Features:\n * Introduce global ``block.basefee`` for retrieving the base fee of the current block.\n * Yul: Introduce builtin ``basefee()`` for retrieving the base fee of the current block.\n\n\nCompiler Features:\n * AssemblyStack: Also run opcode-based optimizer when compiling Yul code.\n * Commandline Interface: option ``--pretty-json`` works also with ``--standard--json``.\n * EVM: Set the default EVM version to \"London\".\n * SMTChecker: Do not check underflow and overflow by default.\n * SMTChecker: Unproved targets are hidden by default, and the SMTChecker only states how many unproved targets there are. They can be listed using the command line option ``--model-checker-show-unproved`` or the JSON option ``settings.modelChecker.showUnproved``.\n * SMTChecker: new setting to enable/disable encoding of division and modulo with slack variables. The command line option is ``--model-checker-div-mod-slacks`` and the JSON option is ``settings.modelChecker.divModWithSlacks``.\n * Yul EVM Code Transform: Also pop unused argument slots for functions without return variables (under the same restrictions as for functions with return variables).\n * Yul EVM Code Transform: Do not reuse stack slots that immediately become unreachable.\n * Yul Optimizer: Move function arguments and return variables to memory with the experimental Stack Limit Evader (which is not enabled by default).\n\n\nBugfixes:\n * Code Generator: Fix crash when passing an empty string literal to ``bytes.concat()``.\n * Code Generator: Fix internal compiler error when calling functions bound to calldata structs and arrays.\n * Code Generator: Fix internal compiler error when passing a 32-byte hex literal or a zero literal to ``bytes.concat()`` by disallowing such literals.\n * Commandline Interface: Apply ``--optimizer-runs`` option in assembly / yul mode.\n * Commandline Interface: Fix crash when a directory path is passed to ``--standard-json``.\n * Commandline Interface: Read JSON from standard input when ``--standard-json`` gets ``-`` as a file name.\n * Standard JSON: Include source location for errors in files with empty name.\n * Type Checker: Fix internal error and prevent static calls to unimplemented modifiers.\n * Yul Code Generator: Fix internal compiler error when using a long literal with bitwise negation.\n * Yul Code Generator: Fix source location references for calls to builtin functions.\n * Yul Parser: Fix source location references for ``if`` statements.\n\n\n### 0.8.6 (2021-06-22)\n\nLanguage Features:\n * Yul: Special meaning of ``\".metadata\"`` data object in Yul object.\n\n\nBugfixes:\n * Control Flow Graph: Fix incorrectly reported unreachable code.\n * Solc-Js: When running ``solcjs`` without the ``--optimize`` flag, use ``settings.optimizer.enabled=false`` in Standard JSON instead of omitting the key.\n * Standard JSON: Omitting ``settings.optimizer.enabled`` was not equivalent to setting it to ``false``. It meant disabling also the peephole optimizer and jumpdest remover which by default still run with ``enabled=false``.\n\n\n### 0.8.5 (2021-06-10)\n\nLanguage Features:\n * Allowing conversion from ``bytes`` and ``bytes`` slices to ``bytes1``/.../``bytes32``.\n * Yul: Add ``verbatim`` builtin function to inject arbitrary bytecode.\n\n\nCompiler Features:\n * Code Generator: Insert helper functions for panic codes instead of inlining unconditionally. This can reduce costs if many panics (checks) are inserted, but can increase costs where few panics are used.\n * EVM: Set the default EVM version to \"Berlin\".\n * SMTChecker: Function definitions can be annotated with the custom Natspec tag ``custom:smtchecker abstract-function-nondet`` to be abstracted by a nondeterministic value when called.\n * Standard JSON / combined JSON: New artifact \"functionDebugData\" that contains bytecode offsets of entry points of functions and potentially more information in the future.\n * Yul Optimizer: Evaluate ``keccak256(a, c)``, when the value at memory location ``a`` is known at compile time and ``c`` is a constant ``<= 32``.\n\n\nBugfixes:\n * AST: Do not output value of Yul literal if it is not a valid UTF-8 string.\n * Code Generator: Fix internal error when function arrays are assigned to storage variables and the function types can be implicitly converted but are not identical.\n * Code Generator: Fix internal error when super would have to skip an unimplemented function in the virtual resolution order.\n * Control Flow Graph: Assume unimplemented modifiers use a placeholder.\n * Control Flow Graph: Take internal calls to functions that always revert into account for reporting unused or unassigned variables.\n * Function Call Graph: Fix internal error connected with circular constant references.\n * Name Resolver: Do not issue shadowing warning if the shadowing name is not directly accessible.\n * Natspec: Allow multiple ``@return`` tags on public state variable documentation.\n * SMTChecker: Fix internal error on conversion from ``bytes`` to ``fixed bytes``.\n * SMTChecker: Fix internal error on external calls from the constructor.\n * SMTChecker: Fix internal error on struct constructor with fixed bytes member initialized with string literal.\n * Source Locations: Properly set source location of scoped blocks.\n * Standard JSON: Properly allow the ``inliner`` setting under ``settings.optimizer.details``.\n * Type Checker: Fix internal compiler error related to having mapping types in constructor parameter for abstract contracts.\n * Type Checker: Fix internal compiler error when attempting to use an invalid external function type on pre-byzantium EVMs.\n * Type Checker: Fix internal compiler error when overriding receive ether function with one having different parameters during inheritance.\n * Type Checker: Make errors about (nested) mapping type in event or error parameter into fatal type errors.\n * Type Checker: Fix internal compiler error when overriding an implemented modifier with an unimplemented one.\n\n\nAST Changes:\n * Add member `hexValue` for Yul string and hex literals.\n\n\n\n### 0.8.4 (2021-04-21)\n\nImportant Bugfixes:\n * ABI Decoder V2: For two-dimensional arrays and specially crafted data in memory, the result of ``abi.decode`` can depend on data elsewhere in memory. Calldata decoding is not affected.\n\n\nLanguage Features:\n * Assembly / Yul: Allow hex string literals.\n * Possibility to use ``bytes.concat`` with variable number of ``bytes`` and ``bytesNN`` arguments which behaves as a restricted version of `abi.encodePacked` with a more descriptive name.\n * Support custom errors via the ``error`` keyword and introduce the ``revert`` statement.\n\n\nCompiler Features:\n * Analysis: Properly detect circular references to the bytecode of other contracts across all function calls.\n * Commandline Interface: Model checker option ``--model-checker-targets`` also accepts ``outOfBounds``.\n * Commandline Interface: New model checker option ``--model-checker-contracts`` allows users to select which contracts should be analyzed as the most derived.\n * Low-Level Inliner: Inline ordinary jumps to small blocks and jumps to small blocks that terminate.\n * NatSpec: Allow ``@notice`` tag on non-public state variables and local variable declarations. The documentation will only be part of the AST, under the field ``documentation``.\n * SMTChecker: Deprecate ``pragma experimental SMTChecker;`` and set default model checker engine to ``none``.\n * SMTChecker: Report local variables in CHC counterexamples.\n * SMTChecker: Report out of bounds index access for arrays and fixed bytes.\n * SMTChecker: Support file level functions and constants.\n * Standard JSON: Model checker option ``settings.modelChecker.targets`` also accepts ``outOfBounds``.\n * Standard JSON: Model checker option ``settings.modelChecker.targets`` takes an array of string targets instead of string of comma separated targets.\n * Standard JSON: New model checker option ``settings.modelChecker.contracts`` allows users to select which contracts should be analyzed as the most derived.\n * Yul EVM Code Transform: Stack Optimization: Reuse slots of unused function arguments and defer allocating stack slots for return variables until after expression statements and assignments that do not reference them.\n * Yul Optimizer: Added a new step FunctionSpecializer, that specializes a function with its literal arguments.\n\n\nBugfixes:\n * Antlr Grammar: Fix parsing of import paths involving properly distinguishing between empty and non-empty string literals in general.\n * AST Output: Fix ``kind`` field of ``ModifierInvocation`` for base constructor calls.\n * Commandline interface: Fix internal error when printing AST and using ``--base-path`` or ``file://`` prefix in imports.\n * Commandline interface: Fix standard input bypassing allowed path checks.\n * Natspec: Fix internal error related to the `@returns` documentation for a public state variable overriding a function.\n * SMTChecker: Fix false positive and false negative on ``push`` as LHS of a compound assignment.\n * SMTChecker: Fix false positive in contracts that cannot be deployed.\n * SMTChecker: Fix internal error on public getter returning dynamic data on older EVM versions where these are not available.\n * SMTChecker: Fix internal error on try-catch with function call in catch block.\n * Type Checker: Fix missing error when events are used without an emit statement.\n\n\nAST Changes:\n * New property for ``ContractDefinition`` nodes: ``usedErrors`` lists AST IDs of all errors used by the contract (even if defined outside).\n\n\n\n### 0.8.3 (2021-03-23)\n\nImportant Bugfixes:\n * Optimizer: Fix bug on incorrect caching of Keccak-256 hashes.\n\nCompiler Features:\n * Command Line Interface: Drop experimental support for ``--machine evm15``.\n * Optimizer: Try to move ``and`` with constant inside ``or`` to improve storage writes of small types.\n * Optimizer: Replace multiplications and divisions with powers of two by shifts.\n\nBugfixes:\n * AST Import: For constructors, a public visibility is ignored during importing.\n * Error Reporter: Fix handling of carriage return.\n * SMTChecker: Fix internal error in BMC on resolving virtual functions inside branches.\n * SMTChecker: Fix internal error on ``array.pop`` nested inside 1-tuple.\n * SMTChecker: Fix internal error on ``FixedBytes`` constant initialized with string literal.\n * SMTChecker: Fix internal error on array slices.\n * SMTChecker: Fix internal error on calling public getter on a state variable of type array (possibly nested) of structs.\n * SMTChecker: Fix internal error on pushing to ``string`` casted to ``bytes``.\n * SMTChecker: Fix bug in virtual functions called by constructors.\n\nAST Changes:\n * ModifierInvocation: Add ``kind`` field which can be ``modifierInvocation`` or ``baseConstructorSpecifier``.\n\n\n### 0.8.2 (2021-03-02)\n\nCompiler Features:\n * AST: Export NatSpec comments above each statement as their documentation.\n * Inline Assembly: Do not warn anymore about variables or functions being shadowed by EVM opcodes.\n * NatSpec: Provide source locations for parsing errors.\n * Optimizer: Simple inlining when jumping to small blocks that jump again after a few side-effect free opcodes.\n * NatSpec: Allow and export all tags that start with ``@custom:``.\n\n\nBugfixes:\n * AST: Added ``referencedDeclaration`` for enum members.\n * Code Generator: Fix internal error when functions are passed as parameters of other callables, when the function types can be implicitly converted, but not identical.\n * Parser: Properly parse ``.address`` in some situations.\n * SMTChecker: Fix missing type constraints on block and transaction variables in the deployment phase.\n * Type Checker: Fix internal error when override specifier is not a contract.\n * Type Checker: Make function-hash collision errors into fatal type errors.\n\n\nAST Changes:\n * Adds ``nameLocation`` to declarations to represent the exact location of the symbolic name.\n * Removed the redundant function type \"bytearraypush\" - replaced by \"arraypush\".\n * Support field ``documentation`` to hold NatSpec comments above each statement.\n\n\n### 0.8.1 (2021-01-27)\n\nLanguage Features:\n * Possibility to use ``catch Panic(uint code)`` to catch a panic failure from an external call.\n\nCompiler Features:\n * Code Generator: Reduce the cost of ``
.code.length`` by using ``extcodesize`` directly.\n * Command Line Interface: Allow ``=`` as separator between library name and address in ``--libraries`` commandline option.\n * Command Line Interface: New option ``--model-checker-targets`` allows specifying which targets should be checked. The valid options are ``all``, ``constantCondition``, ``underflow``, ``overflow``, ``divByZero``, ``balance``, ``assert``, ``popEmptyArray``, where the default is ``all``. Multiple targets can be chosen at the same time, separated by a comma without spaces: ``underflow,overflow,assert``.\n * Command Line Interface: Only accept library addresses with a prefix of ``0x`` in ``--libraries`` commandline option.\n * Optimizer: Add rule to replace ``iszero(sub(x,y))`` by ``eq(x,y)``.\n * Parser: Report meaningful error if parsing a version pragma failed.\n * SMTChecker: Output internal and trusted external function calls in a counterexample's transaction trace.\n * SMTChecker: Show ``msg.value`` in counterexample transaction traces when greater than 0.\n * SMTChecker: Show contract name in counterexample function call.\n * SMTChecker: Support ABI functions as uninterpreted functions.\n * SMTChecker: Support try/catch statements.\n * SMTChecker: Synthesize untrusted functions called externally.\n * SMTChecker: Use checked arithmetic by default and support ``unchecked`` blocks.\n * Standard JSON: New option ``modelCheckerSettings.targets`` allows specifying which targets should be checked. The valid options are ``all``, ``constantCondition``, ``underflow``, ``overflow``, ``divByZero``, ``balance``, ``assert``, ``popEmptyArray``, where the default is ``all``. Multiple targets can be chosen at the same time, separated by a comma without spaces: ``underflow,overflow,assert``.\n\nBugfixes:\n * Code Generator: Fix length check when decoding malformed error data in catch clause.\n * Control Flow Graph: Fix missing error caused by read from/write to uninitialized variables.\n * SMTChecker: Fix false negatives in overriding modifiers and functions.\n * SMTChecker: Fix false negatives in the presence of inline assembly.\n * SMTChecker: Fix false negatives when analyzing external function calls.\n * SMTChecker: Fix internal error on ``block.chainid``.\n * SMTChecker: Fix internal error on pushing string literal to ``bytes`` array.\n * SMTChecker: Fix missing type constraints for block variables.\n * Type Checker: Fix infinite loop when accessing circular constants from inline assembly.\n * Type Checker: Fix internal error caused by constant structs containing mappings.\n * Type System: Disallow implicit conversion from ``uintN`` to ``intM`` when ``M > N``, and by extension, explicit conversion between the same types is also disallowed.\n\nBuild System:\n * Update the soljson.js build to emscripten 2.0.12 and boost 1.75.0.\n\n\n### 0.8.0 (2020-12-16)\n\nBreaking Changes:\n * Code Generator: All arithmetic is checked by default. These checks can be disabled using ``unchecked { ... }``.\n * Code Generator: Cause a panic if a byte array in storage is accessed whose length is encoded incorrectly.\n * Code Generator: Use ``revert`` with error signature ``Panic(uint256)`` and error codes instead of invalid opcode on failing assertions.\n * Command Line Interface: JSON fields `abi`, `devdoc`, `userdoc` and `storage-layout` are now sub-objects rather than strings.\n * Command Line Interface: Remove the ``--old-reporter`` option.\n * Command Line Interface: Remove the legacy ``--ast-json`` option. Only the ``--ast-compact-json`` option is supported now.\n * General: Enable ABI coder v2 by default.\n * General: Remove global functions ``log0``, ``log1``, ``log2``, ``log3`` and ``log4``.\n * Parser: Exponentiation is right associative. ``a**b**c`` is parsed as ``a**(b**c)``.\n * Scanner: Remove support for the ``\\b``, ``\\f``, and ``\\v`` escape sequences.\n * Standard JSON: Remove the ``legacyAST`` option.\n * Type Checker: Function call options can only be given once.\n * Type System: Declarations with the name ``this``, ``super`` and ``_`` are disallowed, with the exception of public functions and events.\n * Type System: Disallow ``msg.data`` in ``receive()`` function.\n * Type System: Disallow ``type(super)``.\n * Type System: Disallow enums with more than 256 members.\n * Type System: Disallow explicit conversions from negative literals and literals larger than ``type(uint160).max`` to ``address`` type.\n * Type System: Disallow the ``byte`` type. It was an alias to ``bytes1``.\n * Type System: Explicit conversion to ``address`` type always returns a non-payable ``address`` type. In particular, ``address(u)``, ``address(b)``, ``address(c)`` and ``address(this)`` have the type ``address`` instead of ``address payable`` (Here ``u``, ``b``, and ``c`` are arbitrary variables of type ``uint160``, ``bytes20`` and contract type respectively.)\n * Type System: Explicit conversions between two types are disallowed if it changes more than one of sign, width or kind at the same time.\n * Type System: Explicit conversions from literals to enums are only allowed if the value fits in the enum.\n * Type System: Explicit conversions from literals to integer type is as strict as implicit conversions.\n * Type System: Introduce ``address(...).code`` to retrieve the code as ``bytes memory``. The size can be obtained via ``address(...).code.length``, but it will currently always include copying the code.\n * Type System: Introduce ``block.chainid`` for retrieving the current chain id.\n * Type System: Support ``address(...).codehash`` to retrieve the codehash of an account.\n * Type System: The global variables ``tx.origin`` and ``msg.sender`` have type ``address`` instead of ``address payable``.\n * Type System: Unary negation can only be used on signed integers, not on unsigned integers.\n * View Pure Checker: Mark ``chainid`` as view.\n * Yul: Disallow the use of reserved identifiers, such as EVM instructions, even if they are not available in the given dialect / EVM version.\n * Yul: The ``assignimmutable`` builtin in the \"EVM with objects\" dialect takes the base offset of the code to modify as an additional argument.\n\nLanguage Features:\n * Super constructors can now be called using the member notation e.g. ``M.C(123)``.\n\nBugfixes:\n * Type Checker: Perform proper truncating integer arithmetic when using constants in array length expressions.\n\nAST Changes:\n * New AST Node ``IdentifierPath`` replacing in many places the ``UserDefinedTypeName``.\n * New AST Node ``UncheckedBlock`` used for ``unchecked { ... }``.\n\n### 0.7.6 (2020-12-16)\n\nLanguage Features:\n * Code generator: Support conversion from calldata slices to memory and storage arrays.\n * Code generator: Support copying dynamically encoded structs from calldata to memory.\n * Code generator: Support copying of nested arrays from calldata to memory.\n * Scanner: Generate a parser error when comments or unicode strings contain an unbalanced or underflowing set of unicode direction override markers (LRO, RLO, LRE, RLE, PDF).\n * The fallback function can now also have a single ``calldata`` argument (equaling ``msg.data``) and return ``bytes memory`` (which will not be ABI-encoded but returned as-is).\n * Wasm backend: Add ``i32.select`` and ``i64.select`` instructions.\n\nCompiler Features:\n * Build System: Optionally support dynamic loading of Z3 and use that mechanism for Linux release builds.\n * Code Generator: Avoid memory allocation for default value if it is not used.\n * SMTChecker: Apply constant evaluation on binary arithmetic expressions.\n * SMTChecker: Create underflow and overflow verification targets for increment/decrement in the CHC engine.\n * SMTChecker: Report struct values in counterexamples from CHC engine.\n * SMTChecker: Support early returns in the CHC engine.\n * SMTChecker: Support getters.\n * SMTChecker: Support named arguments in function calls.\n * SMTChecker: Support struct constructor.\n * Standard-Json: Move the recently introduced ``modelCheckerSettings`` key to ``settings.modelChecker``.\n * Standard-Json: Properly filter the requested output artifacts.\n\nBugfixes:\n * Code generator: Do not pad empty string literals with a single 32-byte zero field in the ABI coder v1.\n * NatSpec: Fix segfault when inheriting return parameter documentation for modifiers with no parameters.\n * SMTChecker: Fix cast string literals to byte arrays.\n * SMTChecker: Fix internal compiler error when doing bitwise compound assignment with string literals.\n * SMTChecker: Fix internal error when trying to generate counterexamples with old z3.\n * SMTChecker: Fix segmentation fault that could occur on certain SMT-enabled sources when no SMT solver was available.\n * SMTChecker: Fix internal error when ``bytes.push()`` is used as the LHS of an assignment.\n * Type Checker: ``super`` is not available in libraries.\n * Type Checker: Disallow leading zeroes in sized-types (e.g. ``bytes000032``), but allow them to be treated as identifiers.\n * Yul Optimizer: Fix a bug in NameSimplifier where a new name created by NameSimplifier could also be created by NameDispenser.\n * Yul Optimizer: Removed NameSimplifier from optimization steps available to users.\n\n### 0.7.5 (2020-11-18)\n\nLanguage Features:\n * Ability to select the abi coder using ``pragma abicoder v1`` and ``pragma abicoder v2``.\n * Inline Assembly: Use ``.offset`` and ``.length`` for calldata variables of dynamic array type to access their calldata offset and length (number of elements). Both of them can also be assigned to.\n * Immutable variables with literal number values are considered pure.\n\nCompiler Features:\n * Assembler: Perform linking in assembly mode when library addresses are provided.\n * Command Line Interface: New option ``--experimental-via-ir`` allows switching compilation process to go through the Yul intermediate representation. This is highly experimental and is used for development purposes.\n * Command Line Interface: New option ``--model-checker-timeout`` sets a timeout in milliseconds for each individual query performed by the SMTChecker.\n * Command Line Interface: Report error if file could not be read in ``--standard-json`` mode.\n * Command Line interface: Report proper error for each output file which could not be written. Previously an exception was thrown, and execution aborted, on the first error.\n * SMTChecker: Add division by zero checks in the CHC engine.\n * SMTChecker: More precise analysis of external calls using ``this``.\n * SMTChecker: Support ``selector`` for expressions with value known at compile-time.\n * Standard JSON: New option ``modelCheckerSettings.timeout`` sets a timeout in milliseconds for each individual query performed by the SMTChecker.\n * Standard JSON: New option ``settings.viaIR`` allows the same switch as ``--experimental-via-ir`` on the commandline.\n\n\nBugfixes:\n * Code generator: Fix missing creation dependency tracking for abstract contracts.\n * Command Line Interface: Fix write error when the directory passed to ``--output-dir`` ends with a slash.\n * Command Line Interface: Reject duplicate libraries in ``--libraries`` option instead of arbitrarily choosing one.\n * NatSpec: Fix internal error when inheriting return parameter documentation but the parameter names differ between base and inherited.\n * SMTChecker: Fix CHC false positives when branches are used inside modifiers.\n * SMTChecker: Fix false negative in modifier applied multiple times.\n * SMTChecker: Fix incorrect counterexamples reported by the CHC engine.\n * SMTChecker: Fix internal error in the BMC engine when inherited contract from a different source unit has private state variables.\n * SMTChecker: Fix internal error on conversion from string literal to byte.\n * SMTChecker: Fix internal error when ``array.push()`` is used as the LHS of an assignment.\n * SMTChecker: Fix internal error when assigning state variable via contract's name.\n * SMTChecker: Fix internal error when using tuples of rational literals inside the conditional operator.\n * SMTChecker: Fix lack of reporting potential violations when using only the CHC engine.\n * Standard JSON: Fix library addresses specified in ``libraries`` being used for linking even if the file names do not match.\n\nAST Changes:\n * New member ``suffix`` for inline assembly identifiers. Currently supported values are ``\"slot\"``, ``\"offset\"`` and ``\"length\"`` to access the components of a Solidity variable.\n\n\n### 0.7.4 (2020-10-19)\n\nImportant Bugfixes:\n * Code Generator: Fix data corruption bug when copying empty byte arrays from memory or calldata to storage.\n\n\nLanguage Features:\n * Constants can be defined at file level.\n\n\nCompiler Features:\n * Command Line Interface: New option ``--model-checker-engine`` allows to choose a specific SMTChecker engine. Options are ``all`` (default), ``bmc``, ``chc`` and ``none``.\n * Control Flow Graph: Print warning for non-empty functions with unnamed return parameters that are not assigned a value in all code paths.\n * SMTChecker: Support ``keccak256``, ``sha256``, ``ripemd160`` and ``ecrecover`` in the CHC engine.\n * SMTChecker: Support inline arrays.\n * SMTChecker: Support variables ``block``, ``msg`` and ``tx`` in the CHC engine.\n * Standard JSON: New option ``modelCheckerSettings.engine`` allows to choose a specific SMTChecker engine. Options are ``all`` (default), ``bmc``, ``chc`` and ``none``.\n\n\nBugfixes:\n * Code generator: Fix ``ABIEncoderV2`` pragma from the current module affecting inherited functions and applied modifiers.\n * Code generator: Fix internal compiler error when referencing members via module name but not using the reference.\n * Code generator: Fix internal error on returning structs containing mappings from library function.\n * Code generator: Use revert instead of invalid opcode for out-of-bounds array index access in getter.\n * Contract Level Checker: Add missing check against inheriting functions with ABIEncoderV2 return types in ABIEncoderV1 contracts.\n * Name Resolver: Fix shadowing/same-name warnings for later declarations.\n * Type Checker: Allow arrays of contract types as type expressions and as arguments for ``abi.decode``.\n * Type Checker: Disallow invalid use of library names as type name.\n * Type Checker: Fix internal compiler error caused by storage parameters with nested mappings in libraries.\n\n\n### 0.7.3 (2020-10-07)\n\nImportant Bugfixes:\n * Code Generator: Properly cleanup after copying dynamic-array to storage for packed types.\n\nCompiler Features:\n * Code generator: Implemented events with function type as one of its indexed parameters.\n * General: Option to stop compilation after parsing stage. Can be used with ``solc --stop-after parsing``\n * Optimizer: Optimize ``exp`` when base is ``-1``.\n * SMTChecker: Support ``addmod`` and ``mulmod``.\n * SMTChecker: Support array slices.\n * SMTChecker: Support type conversions.\n\n\nBugfixes:\n * Fixed internal compiler errors for certain contracts involving the ``new`` expression.\n * JSON AST: Fix internal error when using ``--ast-json`` on a function with memory arguments in ABIEncoderV2 contracts.\n * Type Checker: Add missing checks for calls using types incompatible with ABIEncoderV1 in modules where ABIEncoderV2 is not enabled.\n * Type Checker: Fix internal compiler error when calling `.push()` for a storage array with a nested mapping.\n\n\n### 0.7.2 (2020-09-28)\n\nImportant Bugfixes:\n * Type Checker: Disallow two or more free functions with identical name (potentially imported and aliased) and parameter types.\n\nCompiler Features:\n * Export compiler-generated utility sources via standard-json or combined-json.\n * Optimizer: Optimize ``exp`` when base is 0, 1 or 2.\n * SMTChecker: Keep knowledge about string literals, even through assignment, and thus support the ``.length`` property properly.\n * SMTChecker: Support ``address`` type conversion with literals, e.g. ``address(0)``.\n * SMTChecker: Support ``revert()``.\n * SMTChecker: Support ``type(T).min``, ``type(T).max``, and ``type(I).interfaceId``.\n * SMTChecker: Support compound and, or, and xor operators.\n * SMTChecker: Support events and low-level logs.\n * SMTChecker: Support fixed bytes index access.\n * SMTChecker: Support memory allocation, e.g. ``new bytes(123)``.\n * SMTChecker: Support shifts.\n * SMTChecker: Support structs.\n * Type Checker: Explain why oversized hex string literals can not be explicitly converted to a shorter ``bytesNN`` type.\n * Type Checker: More detailed error messages why implicit conversions fail.\n * Type Checker: Report position of first invalid UTF-8 sequence in ``unicode\"\"`` literals.\n * Yul IR Generator: Report source locations related to unimplemented features.\n * Yul Optimizer: Inline into functions further down in the call graph first.\n * Yul Optimizer: Prune unused parameters in functions.\n * Yul Optimizer: Try to simplify function names.\n\n\nBugfixes:\n * Code generator: Fix internal error on stripping dynamic types from return parameters on EVM versions without ``RETURNDATACOPY``.\n * Type Checker: Add missing check against nested dynamic arrays in ABI encoding functions when ABIEncoderV2 is disabled.\n * Type Checker: Correct the error message for invalid named parameter in a call to refer to the right argument.\n * Type Checker: Disallow ``virtual`` for modifiers in libraries.\n * Name Resolver: Correct the warning for homonymous, but not shadowing declarations.\n * Type system: Fix internal error on implicit conversion of contract instance to the type of its ``super``.\n * Type system: Fix internal error on implicit conversion of string literal to a calldata string.\n * Type system: Fix named parameters in overloaded function and event calls being matched incorrectly if the order differs from the declaration.\n * ViewPureChecker: Prevent visibility check on constructors.\n\n\n### 0.7.1 (2020-09-02)\n\nLanguage Features:\n * Allow function definitions outside of contracts, behaving much like internal library functions.\n * Code generator: Implementing copying structs from calldata to storage.\n\nCompiler Features:\n * SMTChecker: Add underflow and overflow as verification conditions in the CHC engine.\n * SMTChecker: Support bitwise or, xor and not operators.\n * SMTChecker: Support conditional operator.\n * Standard JSON Interface: Do not run EVM bytecode code generation, if only Yul IR or EWasm output is requested.\n * Yul Optimizer: LoopInvariantCodeMotion can move reading operations outside for-loops as long as the affected area is not modified inside the loop.\n * Yul: Report error when using non-string literals for ``datasize()``, ``dataoffset()``, ``linkersymbol()``, ``loadimmutable()``, ``setimmutable()``.\n\nBugfixes:\n * AST: Remove ``null`` member values also when the compiler is used in standard-json-mode.\n * General: Allow `type(Contract).name` for abstract contracts and interfaces.\n * Immutables: Disallow assigning immutables more than once during their declaration.\n * Immutables: Properly treat complex assignment and increment/decrement as both reading and writing and thus disallow it everywhere for immutable variables.\n * Optimizer: Keep side-effects of ``x`` in ``byte(a, shr(b, x))`` even if the constants ``a`` and ``b`` would make the expression zero unconditionally. This optimizer rule is very hard if not impossible to trigger in a way that it can result in invalid code, though.\n * References Resolver: Fix internal bug when using constructor for library.\n * Scanner: Fix bug where whitespace would be allowed within the ``->`` token (e.g. ``function f() - > x {}`` becomes invalid in inline assembly and Yul).\n * SMTChecker: Fix internal error in BMC function inlining.\n * SMTChecker: Fix internal error on array implicit conversion.\n * SMTChecker: Fix internal error on fixed bytes index access.\n * SMTChecker: Fix internal error on lvalue unary operators with tuples.\n * SMTChecker: Fix internal error on tuple assignment.\n * SMTChecker: Fix internal error on tuples of one element that have tuple type.\n * SMTChecker: Fix internal error when using imported code.\n * SMTChecker: Fix soundness of array ``pop``.\n * Type Checker: Disallow ``using for`` directive inside interfaces.\n * Type Checker: Disallow signed literals as exponent in exponentiation operator.\n * Type Checker: Disallow structs containing nested mapping in memory as parameters for library functions.\n * Yul Optimizer: Ensure that Yul keywords are not mistakenly used by the NameDispenser and VarNameCleaners. The bug would manifest as uncompilable code.\n * Yul Optimizer: Make function inlining order more resilient to whether or not unrelated source files are present.\n\n\n### 0.7.0 (2020-07-28)\n\nBreaking changes:\n * Inline Assembly: Disallow ``.`` in user-defined function and variable names.\n * Inline Assembly: Slot and offset of storage pointer variable ``x`` are accessed via ``x.slot`` and ``x.offset`` instead of ``x_slot`` and ``x_offset``.\n * JSON AST: Mark hex string literals with ``kind: \"hexString\"``.\n * JSON AST: Remove members with ``null`` value from JSON output.\n * Parser: Disallow ``gwei`` as identifier.\n * Parser: Disallow dot syntax for ``value`` and ``gas``.\n * Parser: Disallow non-printable characters in string literals.\n * Parser: Introduce Unicode string literals: ``unicode\"😃\"``.\n * Parser: NatSpec comments on variables are only allowed for public state variables.\n * Parser: Remove the ``finney`` and ``szabo`` denominations.\n * Parser: Remove the identifier ``now`` (replaced by ``block.timestamp``).\n * Reference Resolver: ``using A for B`` only affects the contract it is mentioned in and not all derived contracts\n * Type Checker: Disallow ``virtual`` for library functions.\n * Type Checker: Disallow assignments to state variables that contain nested mappings.\n * Type checker: Disallow events with same name and parameter types in inheritance hierarchy.\n * Type Checker: Disallow shifts by signed types.\n * Type Checker: Disallow structs and arrays in memory or calldata if they contain nested mappings.\n * Type Checker: Exponentiation and shifts of literals by non-literals will always use ``uint256`` or ``int256`` as a type.\n * Yul: Disallow consecutive and trailing dots in identifiers. Leading dots were already disallowed.\n * Yul: Disallow EVM instruction `pc()`.\n\n\nLanguage Features:\n * Inheritance: Allow overrides to have stricter state mutability: ``view`` can override ``nonpayable`` and ``pure`` can override ``view``.\n * Parser: Deprecate visibility for constructors.\n * State mutability: Do not issue recommendation for stricter mutability for virtual functions but do issue it for functions that override.\n\n\nCompiler Features:\n * SMTChecker: Report multi-transaction counterexamples including the function calls that initiate the transactions. This does not include concrete values for reference types and reentrant calls.\n * Variable declarations using the ``var`` keyword are not recognized anymore.\n\n\nBugfixes:\n * Immutables: Fix internal compiler error when immutables are not assigned.\n * Inheritance: Disallow public state variables overwriting ``pure`` functions.\n * NatSpec: Constructors and functions have consistent userdoc output.\n * SMTChecker: Fix internal error when assigning to a 1-tuple.\n * SMTChecker: Fix internal error when tuples have extra effectless parenthesis.\n * State Mutability: Constant public state variables are considered ``pure`` functions.\n * Type Checker: Fixing deduction issues on function types when function call has named arguments.\n\n\n### 0.6.12 (2020-07-22)\n\nLanguage Features:\n * NatSpec: Implement tag ``@inheritdoc`` to copy documentation from a specific base contract.\n * Wasm backend: Add ``i32.ctz``, ``i64.ctz``, ``i32.popcnt``, and ``i64.popcnt``.\n\n\nCompiler Features:\n * Code Generator: Avoid double cleanup when copying to memory.\n * Code Generator: Evaluate ``keccak256`` of string literals at compile-time.\n * Optimizer: Add rule to remove shifts inside the byte opcode.\n * Peephole Optimizer: Add rule to remove swap after dup.\n * Peephole Optimizer: Remove unnecessary masking of tags.\n * Yul EVM Code Transform: Free stack slots directly after visiting the right-hand-side of variable declarations instead of at the end of the statement only.\n\n\nBugfixes:\n * SMTChecker: Fix error in events with indices of type static array.\n * SMTChecker: Fix internal error in sequential storage array pushes (``push().push()``).\n * SMTChecker: Fix internal error when using bitwise operators on fixed bytes type.\n * SMTChecker: Fix internal error when using compound bitwise operator assignments on array indices inside branches.\n * Type Checker: Fix internal compiler error related to oversized types.\n * Type Checker: Fix overload resolution in combination with ``{value: ...}``.\n\n\nBuild System:\n * Update internal dependency of jsoncpp to 1.9.3.\n\n\n### 0.6.11 (2020-07-07)\n\n\nLanguage Features:\n * General: Add unit denomination ``gwei``\n * Yul: Support ``linkersymbol`` builtin in standalone assembly mode to refer to library addresses.\n * Yul: Support using string literals exceeding 32 bytes as literal arguments for builtins.\n\n\nCompiler Features:\n * NatSpec: Add fields ``kind`` and ``version`` to the JSON output.\n * NatSpec: Inherit tags from unique base functions if derived function does not provide any.\n * Commandline Interface: Prevent some incompatible commandline options from being used together.\n * NatSpec: Support NatSpec comments on events.\n * Yul Optimizer: Store knowledge about storage / memory after ``a := sload(x)`` / ``a := mload(x)``.\n * SMTChecker: Support external calls to unknown code.\n * Source Maps: Also tag jumps into and out of Yul functions as jumps into and out of functions.\n\n\nBugfixes:\n * NatSpec: Do not consider ``////`` and ``/***`` as NatSpec comments.\n * Type Checker: Disallow constructor parameters with ``calldata`` data location.\n * Type Checker: Do not disallow assigning to calldata variables.\n * Type Checker: Fix internal error related to ``using for`` applied to non-libraries.\n * Wasm backend: Fix code generation for for-loops with pre statements.\n * Wasm backend: Properly support both ``i32.drop`` and ``i64.drop``, and remove ``drop``.\n * Yul: Disallow the same variable to occur multiple times on the left-hand side of an assignment.\n * Yul: Fix source location of variable multi-assignment.\n\n\n### 0.6.10 (2020-06-11)\n\nImportant Bugfixes:\n * Fixed a bug related to internal library functions with ``calldata`` parameters called via ``using for``.\n\n\nCompiler Features:\n * Commandline Interface: Re-group help screen.\n * Output compilation error codes in standard-json and when using ``--error-codes``.\n * Yul: Raise warning for switch statements that only have a default and no other cases.\n\n\nBugfixes:\n * SMTChecker: Fix internal error when encoding tuples of tuples.\n * SMTChecker: Fix aliasing soundness after pushing to an array pointer.\n * Type system: Fix internal compiler error on calling externally a function that returns variables with calldata location.\n * Type system: Fix bug where a bound function was not found if ``using for`` is applied to explicit reference types.\n\n\n### 0.6.9 (2020-06-04)\n\nLanguage Features:\n * Permit calldata location for all variables.\n * NatSpec: Support NatSpec comments on state variables.\n * Yul: EVM instruction `pc()` is marked deprecated and will be removed in the next breaking release.\n\n\nCompiler Features:\n * Build system: Update the soljson.js build to emscripten 1.39.15 and boost 1.73.0 and include Z3 for integrated SMTChecker support without the callback mechanism.\n * Build system: Switch the emscripten build from the fastcomp backend to the upstream backend.\n * Code Generator: Do not introduce new internal source references for small compiler routines.\n * Commandline Interface: Adds new option ``--base-path PATH`` to use the given path as the root of the source tree (defaults to the root of the filesystem).\n * SMTChecker: Support array ``length``.\n * SMTChecker: Support array ``push`` and ``pop``.\n * SMTChecker: General support to BitVectors and the bitwise ``and`` operator.\n\n\nBugfixes:\n * Code Generator: Trigger proper unimplemented errors on certain array copy operations.\n * Commandline Interface: Fix internal error when using ``--assemble`` or ``--yul`` options with ``--machine ewasm`` but without specifying ``--yul-dialect``.\n * NatSpec: DocString block is terminated when encountering an empty line.\n * Optimizer: Fixed a bug in BlockDeDuplicator.\n * Scanner: Fix bug when two empty NatSpec comments lead to scanning past EOL.\n * SMTChecker: Fix internal error on try/catch clauses with parameters.\n * SMTChecker: Fix internal error when applying arithmetic operators to fixed point variables.\n * SMTChecker: Fix internal error when assigning to index access inside branches.\n * SMTChecker: Fix internal error when short circuiting Boolean expressions with function calls in state variable initialization.\n * Type Checker: Disallow assignments to storage variables of type ``mapping``.\n * Type Checker: Disallow inline arrays of non-nameable types.\n * Type Checker: Disallow usage of override with non-public state variables.\n * Type Checker: Fix internal compiler error when accessing members of array slices.\n * Type Checker: Fix internal compiler error when forward referencing non-literal constants from inline assembly.\n * Type Checker: Fix internal compiler error when trying to decode too large static arrays.\n * Type Checker: Fix wrong compiler error when referencing an overridden function without calling it.\n\n\n### 0.6.8 (2020-05-14)\n\nImportant Bugfixes:\n * Add missing callvalue check to the creation code of a contract that does not define a constructor but has a base that does define a constructor.\n * Disallow array slices of arrays with dynamically encoded base types.\n * String literals containing backslash characters can no longer cause incorrect code to be generated when passed directly to function calls or encoding functions when ABIEncoderV2 is active.\n\n\nLanguage Features:\n * Implemented ``type(T).min`` and ``type(T).max`` for every integer type ``T`` that returns the smallest and largest value representable by the type.\n\n\nCompiler Features:\n * Commandline Interface: Don't ignore `--yul-optimizations` in assembly mode.\n * Allow using abi encoding functions for calldata array slices without explicit casts.\n * Wasm binary output: Implement ``br`` and ``br_if``.\n\n\nBugfixes:\n * ABI: Skip ``private`` or ``internal`` constructors.\n * Fixed an \"Assembly Exception in Bytecode\" error where requested functions were generated twice.\n * Natspec: Fixed a bug that ignored ``@return`` tag when no other developer-documentation tags were present.\n * Type Checker: Checks if a literal exponent in the ``**`` operation is too large or fractional.\n * Type Checker: Disallow accessing ``runtimeCode`` for contract types that contain immutable state variables.\n * Yul Assembler: Fix source location of variable declarations without value.\n\n\n### 0.6.7 (2020-05-04)\n\nLanguage Features:\n * Add support for EIP 165 interface identifiers with `type(I).interfaceId`.\n * Allow virtual modifiers inside abstract contracts to have empty body.\n\n\nCompiler Features:\n * Optimizer: Simplify repeated AND and OR operations.\n * Standard Json Input: Support the prefix ``file://`` in the field ``urls``.\n * Add option to specify optimization steps to be performed by Yul optimizer with `--yul-optimizations` in the commandline interface or `optimizer.details.yulDetails.optimizerSteps` in standard-json.\n\nBugfixes:\n * SMTChecker: Fix internal error when fixed points are used.\n * SMTChecker: Fix internal error when using array slices.\n * Type Checker: Disallow ``virtual`` and ``override`` for constructors.\n * Type Checker: Fix several internal errors by performing size and recursiveness checks of types before the full type checking.\n * Type Checker: Fix internal error when assigning to empty tuples.\n * Type Checker: Fix internal error when applying unary operators to tuples with empty components.\n * Type Checker: Perform recursiveness check on structs declared at the file level.\n\nBuild System:\n * soltest.sh: ``SOLIDITY_BUILD_DIR`` is no longer relative to ``REPO_ROOT`` to allow for build directories outside of the source tree.\n\n\n\n### 0.6.6 (2020-04-09)\n\nImportant Bugfixes:\n * Fix tuple assignments with components occupying multiple stack slots and different stack size on left- and right-hand-side.\n\n\nBugfixes:\n * AST export: Export `immutable` property in the field `mutability`.\n * SMTChecker: Fix internal error in the CHC engine when calling inherited functions internally.\n * Type Checker: Error when trying to encode functions with call options gas and value set.\n\n\n\n### 0.6.5 (2020-04-06)\n\nImportant Bugfixes:\n * Code Generator: Restrict the length of dynamic memory arrays to 64 bits during creation at runtime fixing a possible overflow.\n\n\nLanguage Features:\n * Allow local storage variables to be declared without initialization, as long as they are assigned before they are accessed.\n * State variables can be marked ``immutable`` which causes them to be read-only, but assignable in the constructor. The value will be stored directly in the code.\n\n\nCompiler Features:\n * Commandline Interface: Enable output of storage layout with `--storage-layout`.\n * Metadata: Added support for IPFS hashes of large files that need to be split in multiple chunks.\n\n\nBugfixes:\n * Inheritance: Allow public state variables to override functions with dynamic memory types in their return values.\n * Inline Assembly: Fix internal error when accessing invalid constant variables.\n * Inline Assembly: Fix internal error when accessing functions.\n * JSON AST: Always add pointer suffix for memory reference types.\n * Reference Resolver: Fix internal error when accessing invalid struct members.\n * Type Checker: Fix internal errors when assigning nested tuples.\n\n\n### 0.6.4 (2020-03-10)\n\nLanguage Features:\n * General: Deprecated `value(...)` and `gas(...)` in favor of `{value: ...}` and `{gas: ...}`\n * Inline Assembly: Allow assigning to `_slot` of local storage variable pointers.\n * Inline Assembly: Perform control flow analysis on inline assembly. Allows storage returns to be set in assembly only.\n\n\nCompiler Features:\n * AssemblyStack: Support for source locations (source mappings) and thus debugging Yul sources.\n * Commandline Interface: Enable output of experimental optimized IR via ``--ir-optimized``.\n\n\nBugfixes:\n * Inheritance: Fix incorrect error on calling unimplemented base functions.\n * Reference Resolver: Fix scoping issue following try/catch statements.\n * Standard-JSON-Interface: Fix a bug related to empty filenames and imports.\n * SMTChecker: Fix internal errors when analysing tuples.\n * Yul AST Import: correctly import blocks as statements, switch statements and string literals.\n\n### 0.6.3 (2020-02-18)\n\nLanguage Features:\n * Allow contract types and enums as keys for mappings.\n * Allow function selectors to be used as compile-time constants.\n * Report source locations for structured documentation errors.\n\n\nCompiler Features:\n * AST: Add a new node for doxygen-style, structured documentation that can be received by contract, function, event and modifier definitions.\n * Code Generator: Use ``calldatacopy`` instead of ``codecopy`` to zero out memory past input.\n * Debug: Provide reason strings for compiler-generated internal reverts when using the ``--revert-strings`` option or the ``settings.debug.revertStrings`` setting on ``debug`` mode.\n * Yul Optimizer: Prune functions that call each other but are otherwise unreferenced.\n * SMTChecker: CHC support to internal function calls.\n\n\nBugfixes:\n * Assembly: Added missing `source` field to legacy assembly json output to complete the source reference.\n * Parser: Fix an internal error for ``abstract`` without ``contract``.\n * Type Checker: Make invalid calls to uncallable types fatal errors instead of regular.\n\n\n### 0.6.2 (2020-01-27)\n\nLanguage Features:\n * Allow accessing external functions via contract and interface names to obtain their selector.\n * Allow interfaces to inherit from other interfaces\n * Allow gas and value to be set in external function calls using ``c.f{gas: 10000, value: 4 ether}()``.\n * Allow specifying the ``salt`` for contract creations and thus the ``create2`` opcode using ``new C{salt: 0x1234, value: 1 ether}(arg1, arg2)``.\n * Inline Assembly: Support literals ``true`` and ``false``.\n\n\nCompiler Features:\n * LLL: The LLL compiler has been removed.\n * General: Raise warning if runtime bytecode exceeds 24576 bytes (a limit introduced in Spurious Dragon).\n * General: Support compiling starting from an imported AST. Among others, this can be used for mutation testing.\n * Yul Optimizer: Apply penalty when trying to rematerialize into loops.\n\n\nBugfixes:\n * Commandline interface: Only activate yul optimizer if ``--optimize`` is given.\n * Fixes internal compiler error on explicitly calling unimplemented base functions.\n\n\nBuild System:\n * Switch to building soljson.js with an embedded base64-encoded wasm binary.\n\n\n### 0.6.1 (2020-01-02)\n\nBugfixes:\n * Yul Optimizer: Fix bug in redundant assignment remover in combination with break and continue statements.\n\n\n### 0.6.0 (2019-12-17)\n\nBreaking changes:\n * ABI: Remove the deprecated ``constant`` and ``payable`` fields.\n * ABI: The ``type`` field is now required and no longer specified to default to ``function``.\n * AST: Inline assembly is exported as structured JSON instead of plain string.\n * C API (``libsolc``): Introduce context parameter to both ``solidity_compile`` and the callback.\n * C API (``libsolc``): The provided callback now takes two parameters, kind and data. The callback can then be used for multiple purposes, such has file imports and SMT queries.\n * C API (``libsolc``): ``solidity_free`` was renamed to ``solidity_reset``. Functions ``solidity_alloc`` and ``solidity_free`` were added.\n * C API (``libsolc``): ``solidity_compile`` now returns a string that must be explicitly freed via ``solidity_free()``\n * Commandline Interface: Remove the text-based AST printer (``--ast``).\n * Commandline Interface: Switch to the new error reporter by default. ``--old-reporter`` falls back to the deprecated old error reporter.\n * Commandline Interface: Add option to disable or choose hash method between IPFS and Swarm for the bytecode metadata.\n * General: Disallow explicit conversions from external function types to ``address`` and add a member called ``address`` to them as replacement.\n * General: Enable Yul optimizer as part of standard optimization.\n * General: New reserved keywords: ``override``, ``receive``, and ``virtual``.\n * General: ``private`` cannot be used together with ``virtual``.\n * General: Split unnamed fallback functions into two cases defined using ``fallback()`` and ``receive()``.\n * Inheritance: State variable shadowing is now disallowed.\n * Inline Assembly: Only strict inline assembly is allowed.\n * Inline Assembly: Variable declarations cannot shadow declarations outside the assembly block.\n * JSON AST: Replace ``superFunction`` attribute by ``baseFunctions``.\n * Natspec JSON Interface: Properly support multiple ``@return`` statements in ``@dev`` documentation and enforce named return parameters to be mentioned documentation.\n * Source mappings: Add \"modifier depth\" as a fifth field in the source mappings.\n * Standard JSON Interface: Add option to disable or choose hash method between IPFS and Swarm for the bytecode metadata.\n * Syntax: ``push(element)`` for dynamic storage arrays do not return the new length anymore.\n * Syntax: Abstract contracts need to be marked explicitly as abstract by using the ``abstract`` keyword.\n * Syntax: ``length`` member of arrays is now always read-only, even for storage arrays.\n * Type Checker: Resulting type of exponentiation is equal to the type of the base. Also allow signed types for the base.\n\nLanguage Features:\n * Allow explicit conversions from ``address`` to ``address payable`` via ``payable(...)``.\n * Allow global enums and structs.\n * Allow public variables to override external functions.\n * Allow underscores as delimiters in hex strings.\n * Allow to react on failing external calls using ``try`` and ``catch``.\n * Introduce syntax for array slices and implement them for dynamic calldata arrays.\n * Introduce ``push()`` for dynamic storage arrays. It returns a reference to the newly allocated element, if applicable.\n * Introduce ``virtual`` and ``override`` keywords.\n * Modify ``push(element)`` for dynamic storage arrays such that it does not return the new length anymore.\n * Yul: Introduce ``leave`` statement that exits the current function.\n * JSON AST: Add the function selector of each externally-visible FunctionDefinition to the AST JSON export.\n\nCompiler Features:\n * Allow revert strings to be stripped from the binary using the ``--revert-strings`` option or the ``settings.debug.revertStrings`` setting.\n * ABIEncoderV2: Do not warn about enabled ABIEncoderV2 anymore (the pragma is still needed, though).\n\n\n### 0.5.17 (2020-03-17)\n\nBugfixes:\n * Type Checker: Disallow overriding of private functions.\n\n\n### 0.5.16 (2020-01-02)\n\nBackported Bugfixes:\n * Yul Optimizer: Fix bug in redundant assignment remover in combination with break and continue statements.\n\n\n### 0.5.15 (2019-12-17)\n\nBugfixes:\n * Yul Optimizer: Fix incorrect redundant load optimization crossing user-defined functions that contain for-loops with memory / storage writes.\n\n### 0.5.14 (2019-12-09)\n\nLanguage Features:\n * Allow to obtain the selector of public or external library functions via a member ``.selector``.\n * Inline Assembly: Support constants that reference other constants.\n * Parser: Allow splitting hexadecimal and regular string literals into multiple parts.\n\n\nCompiler Features:\n * Commandline Interface: Allow translation from yul / strict assembly to EWasm using ``solc --yul --yul-dialect evm --machine ewasm``\n * Set the default EVM version to \"Istanbul\".\n * SMTChecker: Add support to constructors including constructor inheritance.\n * Yul: When compiling via Yul, string literals from the Solidity code are kept as string literals if every character is safely printable.\n * Yul Optimizer: Perform loop-invariant code motion.\n\n\nBugfixes:\n * SMTChecker: Fix internal error when using ``abi.decode``.\n * SMTChecker: Fix internal error when using arrays or mappings of functions.\n * SMTChecker: Fix internal error in array of structs type.\n * Version Checker: ``^0`` should match ``0.5.0``, but no prerelease.\n * Yul: Consider infinite loops and recursion to be not removable.\n\n\nBuild System:\n * Update to emscripten version 1.39.3.\n\n\n### 0.5.13 (2019-11-14)\n\nLanguage Features:\n * Allow to obtain the address of a linked library with ``address(LibraryName)``.\n\n\nCompiler Features:\n * Code Generator: Use SELFBALANCE opcode for ``address(this).balance`` if using Istanbul EVM.\n * EWasm: Experimental EWasm binary output via ``--ewasm`` and as documented in standard-json.\n * SMTChecker: Add break/continue support to the CHC engine.\n * SMTChecker: Support assignments to multi-dimensional arrays and mappings.\n * SMTChecker: Support inheritance and function overriding.\n * Standard JSON Interface: Output the storage layout of a contract when artifact ``storageLayout`` is requested.\n * TypeChecker: List possible candidates when overload resolution fails.\n * TypeChecker: Disallow variables of library types.\n\nBugfixes:\n * Code Generator: Fixed a faulty assert that would wrongly trigger for array sizes exceeding unsigned integer.\n * SMTChecker: Fix internal error when accessing indices of fixed bytes.\n * SMTChecker: Fix internal error when using function pointers as arguments.\n * SMTChecker: Fix internal error when implicitly converting string literals to fixed bytes.\n * Type Checker: Disallow constructor of the same class to be used as modifier.\n * Type Checker: Treat magic variables as unknown identifiers in inline assembly.\n * Code Generator: Fix internal error when trying to convert ``super`` to a different type\n\n\n### 0.5.12 (2019-10-01)\n\nLanguage Features:\n * Type Checker: Allow assignment to external function arguments except for reference types.\n\n\nCompiler Features:\n * ABI Output: Change sorting order of functions from selector to kind, name.\n * Optimizer: Add rule that replaces the BYTE opcode by 0 if the first argument is larger than 31.\n * SMTChecker: Add loop support to the CHC engine.\n * Yul Optimizer: Take side-effect-freeness of user-defined functions into account.\n * Yul Optimizer: Remove redundant mload/sload operations.\n * Yul Optimizer: Use the fact that branch conditions have certain value inside the branch.\n\n\nBugfixes:\n * Code Generator: Fix internal error when popping a dynamic storage array of mappings.\n * Name Resolver: Fix wrong source location when warning on shadowed aliases in import declarations.\n * Scanner: Fix multi-line natspec comment parsing with triple slashes when file is encoded with CRLF instead of LF.\n * Type System: Fix arrays of recursive structs.\n * Yul Optimizer: Fix reordering bug in connection with shifted one and mul/div-instructions in for loop conditions.\n\n\n### 0.5.11 (2019-08-12)\n\n\nLanguage Features:\n * Inline Assembly: Support direct constants of value type in inline assembly.\n\nCompiler Features:\n * ABI: Additional internal type info in the field ``internalType``.\n * eWasm: Highly experimental eWasm output using ``--ewasm`` in the commandline interface or output selection of ``ewasm.wast`` in standard-json.\n * Metadata: Update the swarm hash to the current specification, changes ``bzzr0`` to ``bzzr1`` and urls to use ``bzz-raw://``.\n * Standard JSON Interface: Compile only selected sources and contracts.\n * Standard JSON Interface: Provide secondary error locations (e.g. the source position of other conflicting declarations).\n * SMTChecker: Do not erase knowledge about storage pointers if another storage pointer is assigned.\n * SMTChecker: Support string literal type.\n * SMTChecker: New Horn-based algorithm that proves assertions via multi-transaction contract invariants.\n * Standard JSON Interface: Provide AST even on errors if ``--error-recovery`` commandline switch or StandardCompiler `settings.parserErrorRecovery` is true.\n * Yul Optimizer: Do not inline function if it would result in expressions being duplicated that are not cheap.\n\n\nBugfixes:\n * ABI decoder: Ensure that decoded arrays always point to distinct memory locations.\n * Code Generator: Treat dynamically encoded but statically sized arrays and structs in calldata properly.\n * SMTChecker: Fix internal error when inlining functions that contain tuple expressions.\n * SMTChecker: Fix pointer knowledge erasing in loops.\n * SMTChecker: Fix internal error when using compound bitwise assignment operators inside branches.\n * SMTChecker: Fix internal error when inlining a function that returns a tuple containing an unsupported type inside a branch.\n * SMTChecker: Fix internal error when inlining functions that use state variables and belong to a different source.\n * SMTChecker: Fix internal error when reporting counterexamples concerning state variables from different source files.\n * SMTChecker: Fix SMT sort mismatch when using string literals.\n * View/Pure Checker: Properly detect state variable access through base class.\n * Yul Analyzer: Check availability of data objects already in analysis phase.\n * Yul Optimizer: Fix an issue where memory-accessing code was removed even though ``msize`` was used in the program.\n\n\n### 0.5.10 (2019-06-25)\n\nImportant Bugfixes:\n * ABIEncoderV2: Fix incorrect abi encoding of storage array of data type that occupy multiple storage slots\n * Code Generator: Properly zero out higher order bits in elements of an array of negative numbers when assigning to storage and converting the type at the same time.\n\n\nCompiler Features:\n * Commandline Interface: Experimental parser error recovery via the ``--error-recovery`` commandline switch or StandardCompiler `settings.parserErrorRecovery` boolean.\n * Optimizer: Add rule to simplify ``SUB(~0, X)`` to ``NOT(X)``.\n * Yul Optimizer: Make the optimizer work for all dialects of Yul including eWasm.\n\n\nBugfixes:\n * Type Checker: Set state mutability of the function type members ``gas`` and ``value`` to pure (while their return type inherits state mutability from the function type).\n * Yul / Inline Assembly Parser: Disallow trailing commas in function call arguments.\n\n\nBuild System:\n * Attempt to use stock Z3 cmake files to find Z3 and only fall back to manual discovery.\n * CMake: use imported targets for boost.\n * Emscripten build: upgrade to boost 1.70.\n * Generate a cmake error for gcc versions older than 5.0.\n\n\n\n### 0.5.9 (2019-05-28)\n\nLanguage Features:\n * Inline Assembly: Revert change introduced in 0.5.7: The ``callvalue()`` instruction does not require ``payable`` anymore.\n * Static Analyzer: Disallow libraries calling themselves externally.\n\n\nCompiler Features:\n * Assembler: Encode the compiler version in the deployed bytecode.\n * Code Generator: Fix handling of structs of dynamic size as constructor parameters.\n * Inline Assembly: Disallow the combination of ``msize()`` and the Yul optimizer.\n * Metadata: Add IPFS hashes of source files.\n * Optimizer: Add rule to simplify SHL/SHR combinations.\n * Optimizer: Add rules for multiplication and division by left-shifted one.\n * SMTChecker: Support inherited state variables.\n * SMTChecker: Support tuples and function calls with multiple return values.\n * SMTChecker: Support ``delete``.\n * SMTChecker: Inline external function calls to ``this``.\n * Yul Optimizer: Simplify single-run ``for`` loops to ``if`` statements.\n * Yul Optimizer: Optimize representation of numbers.\n * Yul Optimizer: Do not inline recursive functions.\n * Yul Optimizer: Do not remove instructions that affect ``msize()`` if ``msize()`` is used.\n\nBugfixes:\n * Code Generator: Explicitly turn uninitialized internal function pointers into invalid functions when loaded from storage.\n * Code Generator: Fix assertion failure when assigning structs containing array of mapping.\n * Compiler Internals: Reset the Yul string repository before each compilation, freeing up memory.\n * SMTChecker: Fix bad cast in base constructor modifier.\n * SMTChecker: Fix internal error when visiting state variable inherited from base class.\n * SMTChecker: Fix internal error in fixed point operations.\n * SMTChecker: Fix internal error in assignment to unsupported type.\n * SMTChecker: Fix internal error in branching when inlining function calls that modify local variables.\n\n\n### 0.5.8 (2019-04-30)\n\nImportant Bugfixes:\n * Code Generator: Fix initialization routine of uninitialized internal function pointers in constructor context.\n * Yul Optimizer: Fix SSA transform for multi-assignments.\n\n\nLanguage Features:\n * ABIEncoderV2: Implement encoding of calldata arrays and structs.\n * Code Generation: Implement copying recursive structs from storage to memory.\n * Yul: Disallow function definitions inside for-loop init blocks.\n\n\nCompiler Features:\n * ABI Decoder: Raise a runtime error on dirty inputs when using the experimental decoder.\n * Optimizer: Add rule for shifts by constants larger than 255 for Constantinople.\n * Optimizer: Add rule to simplify certain ANDs and SHL combinations\n * SMTChecker: Support arithmetic compound assignment operators.\n * SMTChecker: Support unary increment and decrement for array and mapping access.\n * SMTChecker: Show unsupported warning for inline assembly blocks.\n * SMTChecker: Support mod.\n * SMTChecker: Support ``contract`` type.\n * SMTChecker: Support ``this`` as address.\n * SMTChecker: Support address members.\n * Standard JSON Interface: Metadata settings now re-produce the original ``\"useLiteralContent\"`` setting from the compilation input.\n * Yul: Adds break and continue keywords to for-loop syntax.\n * Yul: Support ``.`` as part of identifiers.\n * Yul Optimizer: Adds steps for detecting and removing of dead code.\n * Yul Code Generator: Directly jump over a series of function definitions (instead of jumping over each one)\n\n\nBugfixes:\n * SMTChecker: Implement Boolean short-circuiting.\n * SMTChecker: SSA control-flow did not take into account state variables that were modified inside inlined functions that were called inside branches.\n * Type System: Use correct type name for contracts in event parameters when used in libraries. This affected code generation.\n * Type System: Allow direct call to base class functions that have overloads.\n * Type System: Warn about shadowing builtin variables if user variables are named ``this`` or ``super``.\n * Yul: Properly register functions and disallow shadowing between function variables and variables in the outside scope.\n\n\nBuild System:\n * Soltest: Add commandline option `--test` / `-t` to isoltest which takes a string that allows filtering unit tests.\n * soltest.sh: allow environment variable ``SOLIDITY_BUILD_DIR`` to specify build folder and add ``--help`` usage.\n\n\n### 0.5.7 (2019-03-26)\n\nImportant Bugfixes:\n * ABIEncoderV2: Fix bugs related to loading short value types from storage when encoding an array or struct from storage.\n * ABIEncoderV2: Fix buffer overflow problem when encoding packed array from storage.\n * Optimizer: Fix wrong ordering of arguments in byte optimization rule for constants.\n\n\nLanguage Features:\n * Function calls with named arguments now work with overloaded functions.\n\n\nCompiler Features:\n * Inline Assembly: Issue error when using ``callvalue()`` inside nonpayable function (in the same way that ``msg.value`` already does).\n * Standard JSON Interface: Support \"Yul\" as input language.\n * SMTChecker: Show callstack together with model if applicable.\n * SMTChecker: Support modifiers.\n * Yul Optimizer: Enable stack allocation optimization by default if Yul optimizer is active (disable in ``yulDetails``).\n\n\nBugfixes:\n * Code Generator: Defensively pad memory for ``type(Contract).name`` to multiples of 32.\n * Type System: Detect and disallow internal function pointers as parameters for public/external library functions, even when they are nested/wrapped in structs, arrays or other types.\n * Yul Optimizer: Properly determine whether a variable can be eliminated during stack compression pass.\n * Yul / Inline Assembly Parser: Disallow more than one case statement with the same label inside a switch based on the label's integer value.\n\n\nBuild System:\n * Install scripts: Fix boost repository URL for CentOS 6.\n * Soltest: Fix hex string update in soltest.\n\n\n### 0.5.6 (2019-03-13)\n\nImportant Bugfixes:\n * Yul Optimizer: Fix visitation order bug for the structural simplifier.\n * Optimizer: Fix overflow in optimization rule that simplifies double shift by constant.\n\nLanguage Features:\n * Allow calldata arrays with dynamically encoded base types with ABIEncoderV2.\n * Allow dynamically encoded calldata structs with ABIEncoderV2.\n\n\nCompiler Features:\n * Optimizer: Add rules for ``lt``-comparisons with constants.\n * Peephole Optimizer: Remove double ``iszero`` before ``jumpi``.\n * SMTChecker: Support enums without typecast.\n * SMTChecker: Support one-dimensional arrays.\n * Type Checker: Provide better error messages for some literal conversions.\n * Yul Optimizer: Add rule to remove empty default switch cases.\n * Yul Optimizer: Add rule to remove empty cases if no default exists.\n * Yul Optimizer: Add rule to replace a switch with no cases with ``pop(expression)``.\n\n\nBugfixes:\n * JSON ABI: Json description of library ABIs no longer contains functions with internal types like storage structs.\n * SMTChecker: Fix internal compiler error when contract contains too large rational number.\n * Type system: Detect if a contract's base uses types that require the experimental abi encoder while the contract still uses the old encoder.\n\n\nBuild System:\n * Soltest: Add support for arrays in function signatures.\n * Soltest: Add support for struct arrays in function signatures.\n * Soltest: Add support for left-aligned, unpadded hex string literals.\n\n### 0.5.5 (2019-03-05)\n\nLanguage Features:\n * Add support for getters of mappings with ``string`` or ``bytes`` key types.\n * Meta programming: Provide access to the name of contracts via ``type(C).name``.\n\n\nCompiler Features:\n * Support ``petersburg`` as ``evmVersion`` and set as default.\n * Commandline Interface: Option to activate the experimental yul optimizer using ``-optimize-yul``.\n * Inline Assembly: Consider ``extcodehash`` as part of Constantinople.\n * Inline Assembly: Instructions unavailable to the currently configured EVM are errors now.\n * SMTChecker: Do not report underflow/overflow if they always revert. This removes false positives when using ``SafeMath``.\n * Standard JSON Interface: Allow retrieving metadata without triggering bytecode generation.\n * Standard JSON Interface: Provide fine-grained control over the optimizer via the settings.\n * Static Analyzer: Warn about expressions with custom types when they have no effect.\n * Optimizer: Add new rules with constants including ``LT``, ``GT``, ``AND`` and ``BYTE``.\n * Optimizer: Add rule for shifts with constants for Constantinople.\n * Optimizer: Combine multiple shifts with constant shift-by values into one.\n * Optimizer: Do not mask with 160-bits after ``CREATE`` and ``CREATE2`` as they are guaranteed to return an address or 0.\n * Optimizer: Support shifts in the constant optimiser for Constantinople.\n * Yul Optimizer: Add rule to replace switch statements with literals by matching case body.\n\n\nBugfixes:\n * ABIEncoderV2: Fix internal error related to bare delegatecall.\n * ABIEncoderV2: Fix internal error related to ecrecover.\n * ABIEncoderV2: Fix internal error related to mappings as library parameters.\n * ABIEncoderV2: Fix invalid signature for events containing structs emitted in libraries.\n * Inline Assembly: Proper error message for missing variables.\n * Optimizer: Fix internal error related to unused tag removal across assemblies. This never generated any invalid code.\n * SMTChecker: Fix crash related to statically-sized arrays.\n * TypeChecker: Fix internal error and disallow index access on contracts and libraries.\n * Yul: Properly detect name clashes with functions before their declaration.\n * Yul: Take built-in functions into account in the compilability checker.\n * Yul Optimizer: Properly take reassignments to variables in sub-expressions into account when replacing in the ExpressionSimplifier.\n\n\nBuild System:\n * Soltest: Add support for left-aligned, padded hex literals.\n * Soltest: Add support for right-aligned, padded boolean literals.\n\n### 0.5.4 (2019-02-12)\n\nLanguage Features:\n * Allow calldata structs without dynamically encoded members with ABIEncoderV2.\n\n\nCompiler Features:\n * ABIEncoderV2: Implement packed encoding.\n * C API (``libsolc`` / raw ``soljson.js``): Introduce ``solidity_free`` method which releases all internal buffers to save memory.\n * Commandline Interface: Adds new option ``--new-reporter`` for improved diagnostics formatting\n along with ``--color`` and ``--no-color`` for colorized output to be forced (or explicitly disabled).\n\n\nBugfixes:\n * Code Generator: Defensively pad allocation of creationCode and runtimeCode to multiples of 32 bytes.\n * Commandline Interface: Allow yul optimizer only for strict assembly.\n * Parser: Disallow empty import statements.\n * Type Checker: Disallow mappings with data locations other than ``storage``.\n * Type Checker: Fix internal error when a struct array index does not fit into a uint256.\n * Type System: Properly report packed encoded size for arrays and structs (mostly unused until now).\n\n\nBuild System:\n * Add support for continuous fuzzing via Google oss-fuzz\n * SMT: If using Z3, require version 4.6.0 or newer.\n * Soltest: Add parser that is used in the file-based unit test environment.\n * Ubuntu PPA Packages: Use CVC4 as SMT solver instead of Z3\n\n\n### 0.5.3 (2019-01-22)\n\nLanguage Features:\n * Provide access to creation and runtime code of contracts via ``type(C).creationCode`` / ``type(C).runtimeCode``.\n\n\nCompiler Features:\n * Control Flow Graph: Warn about unreachable code.\n * SMTChecker: Support basic typecasts without truncation.\n * SMTChecker: Support external function calls and erase all knowledge regarding storage variables and references.\n\n\nBugfixes:\n * Emscripten: Split simplification rule initialization up further to work around issues with soljson.js in some browsers.\n * Type Checker: Disallow calldata structs until implemented.\n * Type Checker: Return type error if fixed point encoding is attempted instead of throwing ``UnimplementedFeatureError``.\n * Yul: Check that arguments to ``dataoffset`` and ``datasize`` are literals at parse time and properly take this into account in the optimizer.\n * Yul: Parse number literals for detecting duplicate switch cases.\n * Yul: Require switch cases to have the same type.\n\n\nBuild System:\n * Emscripten: Upgrade to emscripten 1.38.8 on travis and circleci.\n\n\n### 0.5.2 (2018-12-19)\n\nLanguage Features:\n * Control Flow Graph: Detect every access to uninitialized storage pointers.\n\n\nCompiler Features:\n * Inline Assembly: Improve error messages around invalid function argument count.\n * Code Generator: Only check callvalue once if all functions are non-payable.\n * Code Generator: Use codecopy for string constants more aggressively.\n * Code Generator: Use binary search for dispatch function if more efficient. The size/speed tradeoff can be tuned using ``--optimize-runs``.\n * SMTChecker: Support mathematical and cryptographic functions in an uninterpreted way.\n * SMTChecker: Support one-dimensional mappings.\n * Standard JSON Interface: Disallow unknown keys in standard JSON input.\n * Standard JSON Interface: Only run code generation if it has been requested. This could lead to unsupported feature errors only being reported at the point where you request bytecode.\n * Static Analyzer: Do not warn about unused variables or state mutability for functions with an empty body.\n * Type Checker: Add an additional reason to be displayed when type conversion fails.\n * Yul: Support object access via ``datasize``, ``dataoffset`` and ``datacopy`` in standalone assembly mode.\n\n\nBugfixes:\n * Standard JSON Interface: Report specific error message for json input errors instead of internal compiler error.\n\n\nBuild System:\n * Replace the trusty PPA build by a static build on cosmic that is used for the trusty package instead.\n * Remove support for Visual Studio 2015.\n\n\n### 0.5.1 (2018-12-03)\n\nLanguage Features:\n * Allow mapping type for parameters and return variables of public and external library functions.\n * Allow public functions to override external functions.\n\nCompiler Features:\n * Code generator: Do not perform redundant double cleanup on unsigned integers when loading from calldata.\n * Commandline interface: Experimental ``--optimize`` option for assembly mode (``--strict-assembly`` and ``--yul``).\n * SMTChecker: SMTLib2 queries and responses passed via standard JSON compiler interface.\n * SMTChecker: Support ``msg``, ``tx`` and ``block`` member variables.\n * SMTChecker: Support ``gasleft()`` and ``blockhash()`` functions.\n * SMTChecker: Support internal bound function calls.\n * Yul: Support Yul objects in ``--assemble``, ``--strict-assembly`` and ``--yul`` commandline options.\n\nBugfixes:\n * Assembly output: Do not mix in/out jump annotations with arguments.\n * Commandline interface: Fix crash when using ``--ast`` on empty runtime code.\n * Code Generator: Annotate jump from calldata decoder to function as \"jump in\".\n * Code Generator: Fix internal error related to state variables of function type access via base contract name.\n * Optimizer: Fix nondeterminism bug related to the boost version and constants representation. The bug only resulted in less optimal but still correct code because the generated routine is always verified to be correct.\n * Type Checker: Properly detect different return types when overriding an external interface function with a public contract function.\n * Type Checker: Disallow struct return types for getters of public state variables unless the new ABI encoder is active.\n * Type Checker: Fix internal compiler error when a field of a struct used as a parameter in a function type has a non-existent type.\n * Type Checker: Disallow functions ``sha3`` and ``suicide`` also without a function call.\n * Type Checker: Fix internal compiler error with ``super`` when base contract function is not implemented.\n * Type Checker: Fixed internal error when trying to create abstract contract in some cases.\n * Type Checker: Fixed internal error related to double declaration of events.\n * Type Checker: Disallow inline arrays of mapping type.\n * Type Checker: Consider abstract function to be implemented by public state variable.\n\nBuild System:\n * CMake: LLL is not built anymore by default. Must configure it with CMake as `-DLLL=ON`.\n * Docker: Includes both Scratch and Alpine images.\n * Emscripten: Upgrade to Emscripten SDK 1.37.21 and boost 1.67.\n\nSolc-Js:\n * Fix handling of standard-json in the commandline executable.\n * Remove support of nodejs 4.\n\n\n### 0.5.0 (2018-11-13)\n\nHow to update your code:\n * Change every ``.call()`` to a ``.call(\"\")`` and every ``.call(signature, a, b, c)`` to use ``.call(abi.encodeWithSignature(signature, a, b, c))`` (the last one only works for value types).\n * Change every ``keccak256(a, b, c)`` to ``keccak256(abi.encodePacked(a, b, c))``.\n * Add ``public`` to every function and ``external`` to every fallback or interface function that does not specify its visibility already.\n * Make your fallback functions ``external``.\n * Explicitly state the data location for all variables of struct, array or mapping types (including function parameters), e.g. change ``uint[] x = m_x`` to ``uint[] storage x = m_x``. Note that ``external`` functions require parameters with a data location of ``calldata``.\n * Explicitly convert values of contract type to addresses before using an ``address`` member. Example: if ``c`` is a contract, change ``c.transfer(...)`` to ``address(c).transfer(...)``.\n * Declare variables and especially function arguments as ``address payable``, if you want to call ``transfer`` on them.\n\nBreaking Changes:\n * ABI Encoder: Properly pad data from calldata (``msg.data`` and external function parameters). Use ``abi.encodePacked`` for unpadded encoding.\n * C API (``libsolc`` / raw ``soljson.js``): Removed the ``version``, ``license``, ``compileSingle``, ``compileJSON``, ``compileJSONCallback`` methods\n and replaced them with the ``solidity_license``, ``solidity_version`` and ``solidity_compile`` methods.\n * Code Generator: Signed right shift uses proper arithmetic shift, i.e. rounding towards negative infinity. Warning: this may silently change the semantics of existing code!\n * Code Generator: Revert at runtime if calldata is too short or points out of bounds. This is done inside the ``ABI decoder`` and therefore also applies to ``abi.decode()``.\n * Code Generator: Use ``STATICCALL`` for ``pure`` and ``view`` functions. This was already the case in the experimental 0.5.0 mode.\n * Commandline interface: Remove obsolete ``--formal`` option.\n * Commandline interface: Rename the ``--julia`` option to ``--yul``.\n * Commandline interface: Require ``-`` if standard input is used as source.\n * Commandline interface: Use hash of library name for link placeholder instead of name itself.\n * Compiler interface: Disallow remappings with empty prefix.\n * Control Flow Analyzer: Consider mappings as well when checking for uninitialized return values.\n * Control Flow Analyzer: Turn warning about returning uninitialized storage pointers into an error.\n * General: ``continue`` in a ``do...while`` loop jumps to the condition (it used to jump to the loop body). Warning: this may silently change the semantics of existing code.\n * General: Disallow declaring empty structs.\n * General: Disallow raw ``callcode`` (was already deprecated in 0.4.12). It is still possible to use it via inline assembly.\n * General: Disallow ``var`` keyword.\n * General: Disallow ``sha3`` and ``suicide`` aliases.\n * General: Disallow the ``throw`` statement. This was already the case in the experimental 0.5.0 mode.\n * General: Disallow the ``years`` unit denomination (was already deprecated in 0.4.24)\n * General: Introduce ``emit`` as a keyword instead of parsing it as identifier.\n * General: New keywords: ``calldata`` and ``constructor``\n * General: New reserved keywords: ``alias``, ``apply``, ``auto``, ``copyof``, ``define``, ``immutable``,\n ``implements``, ``macro``, ``mutable``, ``override``, ``partial``, ``promise``, ``reference``, ``sealed``,\n ``sizeof``, ``supports``, ``typedef`` and ``unchecked``.\n * General: Remove assembly instruction aliases ``sha3`` and ``suicide``\n * General: C99-style scoping rules are enforced now. This was already the case in the experimental 0.5.0 mode.\n * General: Disallow combining hex numbers with unit denominations (e.g. ``0x1e wei``). This was already the case in the experimental 0.5.0 mode.\n * JSON AST: Remove ``constant`` and ``payable`` fields (the information is encoded in the ``stateMutability`` field).\n * JSON AST: Replace the ``isConstructor`` field by a new ``kind`` field, which can be ``constructor``, ``fallback`` or ``function``.\n * Interface: Remove \"clone contract\" feature. The ``--clone-bin`` and ``--combined-json clone-bin`` commandline options are not available anymore.\n * Name Resolver: Do not exclude public state variables when looking for conflicting declarations.\n * Optimizer: Remove the no-op ``PUSH1 0 NOT AND`` sequence.\n * Parser: Disallow trailing dots that are not followed by a number.\n * Parser: Remove ``constant`` as function state mutability modifier.\n * Parser: Disallow uppercase X in hex number literals\n * Type Checker: Disallow assignments between tuples with different numbers of components. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Disallow values for constants that are not compile-time constants. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Disallow arithmetic operations for boolean variables.\n * Type Checker: Disallow tight packing of literals. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Disallow calling base constructors without parentheses. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Disallow conversions between ``bytesX`` and ``uintY`` of different size.\n * Type Checker: Disallow conversions between unrelated contract types. Explicit conversion via ``address`` can still achieve it.\n * Type Checker: Disallow empty return statements for functions with one or more return values.\n * Type Checker: Disallow empty tuple components. This was partly already the case in the experimental 0.5.0 mode.\n * Type Checker: Disallow multi-variable declarations with mismatching number of values. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Disallow specifying base constructor arguments multiple times in the same inheritance hierarchy. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Disallow calling constructor with wrong argument count. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Disallow uninitialized storage variables. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Detecting cyclic dependencies in variables and structs is limited in recursion to 256.\n * Type Checker: Require explicit data location for all variables, including function parameters. This was partly already the case in the experimental 0.5.0 mode.\n * Type Checker: Only accept a single ``bytes`` type for ``.call()`` (and family), ``keccak256()``, ``sha256()`` and ``ripemd160()``.\n * Type Checker: Fallback function must be external. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Interface functions must be declared external. This was already the case in the experimental 0.5.0 mode.\n * Type Checker: Address members are not included in contract types anymore. An explicit conversion is now required before invoking an ``address`` member from a contract.\n * Type Checker: Disallow \"loose assembly\" syntax entirely. This means that jump labels, jumps and non-functional instructions cannot be used anymore.\n * Type System: Disallow explicit and implicit conversions from decimal literals to ``bytesXX`` types.\n * Type System: Disallow explicit and implicit conversions from hex literals to ``bytesXX`` types of different size.\n * Type System: Distinguish between payable and non-payable address types.\n * View Pure Checker: Disallow ``msg.value`` in (or introducing it via a modifier to) a non-payable function.\n * Remove obsolete ``std`` directory from the Solidity repository. This means accessing ``https://github.com/ethereum/solidity/blob/develop/std/*.sol`` (or ``https://github.com/ethereum/solidity/std/*.sol`` in Remix) will not be possible.\n * References Resolver: Turn missing storage locations into an error. This was already the case in the experimental 0.5.0 mode.\n * Syntax Checker: Disallow functions without implementation to use modifiers. This was already the case in the experimental 0.5.0 mode.\n * Syntax Checker: Named return values in function types are an error.\n * Syntax Checker: Strictly require visibility specifier for functions. This was already the case in the experimental 0.5.0 mode.\n * Syntax Checker: Disallow unary ``+``. This was already the case in the experimental 0.5.0 mode.\n * Syntax Checker: Disallow single statement variable declaration inside if/while/for bodies that are not blocks.\n * View Pure Checker: Strictly enforce state mutability. This was already the case in the experimental 0.5.0 mode.\n\nLanguage Features:\n * General: Add ``staticcall`` to ``address``.\n * General: Allow appending ``calldata`` keyword to types, to explicitly specify data location for arguments of external functions.\n * General: Support ``pop()`` for storage arrays.\n * General: Scoping rules now follow the C99-style.\n * General: Allow ``enum``s in interfaces.\n * General: Allow ``mapping`` storage pointers as arguments and return values in all internal functions.\n * General: Allow ``struct``s in interfaces.\n * General: Provide access to the ABI decoder through ``abi.decode(bytes memory data, (...))``.\n * General: Disallow zero length for fixed-size arrays.\n * Parser: Accept the ``address payable`` type during parsing.\n\nCompiler Features:\n * Build System: Support for Mojave version of macOS added.\n * Code Generator: ``CREATE2`` instruction has been updated to match EIP1014 (aka \"Skinny CREATE2\"). It also is accepted as part of Constantinople.\n * Code Generator: ``EXTCODEHASH`` instruction has been added based on EIP1052.\n * Type Checker: Nicer error message when trying to reference overloaded identifiers in inline assembly.\n * Type Checker: Show named argument in case of error.\n * Type System: IntegerType is split into IntegerType and AddressType internally.\n * Tests: Determine transaction status during IPC calls.\n * Code Generator: Allocate and free local variables according to their scope.\n * Removed ``pragma experimental \"v0.5.0\";``.\n * Syntax Checker: Improved error message for lookup in function types.\n * Name Resolver: Updated name suggestion look up function to take into account length of the identifier: 1: no search, 2-3: at most one change, 4-: at most two changes\n * SMTChecker: Support calls to internal functions that return none or a single value.\n\nBugfixes:\n * Build System: Support versions of CVC4 linked against CLN instead of GMP. In case of compilation issues due to the experimental SMT solver support, the solvers can be disabled when configuring the project with CMake using ``-DUSE_CVC4=OFF`` or ``-DUSE_Z3=OFF``.\n * Tests: Fix chain parameters to make ipc tests work with newer versions of cpp-ethereum.\n * Code Generator: Fix allocation of byte arrays (zeroed out too much memory).\n * Code Generator: Properly handle negative number literals in ABIEncoderV2.\n * Code Generator: Do not crash on using a length of zero for multidimensional fixed-size arrays.\n * Commandline Interface: Correctly handle paths with backslashes on windows.\n * Control Flow Analyzer: Ignore unimplemented functions when detecting uninitialized storage pointer returns.\n * Fix NatSpec json output for `@notice` and `@dev` tags on contract definitions.\n * Optimizer: Correctly estimate gas costs of constants for special cases.\n * Optimizer: Fix simplification rule initialization bug that appeared on some emscripten platforms.\n * References Resolver: Do not crash on using ``_slot`` and ``_offset`` suffixes on their own.\n * References Resolver: Enforce ``storage`` as data location for mappings.\n * References Resolver: Properly handle invalid references used together with ``_slot`` and ``_offset``.\n * References Resolver: Report error instead of assertion fail when FunctionType has an undeclared type as parameter.\n * References Resolver: Fix high CPU usage when using large variable names issue. Only suggest similar name if identifiers shorter than 80 characters.\n * Type Checker: Default data location for type conversions (e.g. from literals) is memory and not storage.\n * Type Checker: Disallow assignments to mappings within tuple assignments as well.\n * Type Checker: Disallow packed encoding of arrays of structs.\n * Type Checker: Allow assignments to local variables of mapping types.\n * Type Checker: Consider fixed size arrays when checking for recursive structs.\n * Type Checker: Fix crashes in erroneous tuple assignments in which the type of the right hand side cannot be determined.\n * Type Checker: Fix freeze for negative fixed-point literals very close to ``0``, such as ``-1e-100``.\n * Type Checker: Dynamic types as key for public mappings return error instead of assertion fail.\n * Type Checker: Fix internal error when array index value is too large.\n * Type Checker: Fix internal error when fixed-size array is too large to be encoded.\n * Type Checker: Fix internal error for array type conversions.\n * Type Checker: Fix internal error when array index is not an unsigned.\n * Type System: Allow arbitrary exponents for literals with a mantissa of zero.\n * Parser: Fix incorrect source location for nameless parameters.\n * Command Line Interface: Fix internal error when compiling stdin with no content and --ast option.\n\n\n### 0.4.26 (2019-04-29)\n\nImportant Bugfixes:\n * Code Generator: Fix initialization routine of uninitialized internal function pointers in constructor context.\n * Type System: Use correct type name for contracts in event parameters when used in libraries. This affected code generation.\n\nBugfixes:\n * ABIEncoderV2: Refuse to generate code that is known to be potentially buggy.\n * General: Split rule list such that JavaScript environments with small stacks can use the compiler.\n\nNote: The above changes are not included in 0.5.0, because they were backported.\n\n\n### 0.4.25 (2018-09-12)\n\nImportant Bugfixes:\n * Code Generator: Properly perform cleanup for exponentiation and non-256 bit types.\n * Type Checker: Report error when using indexed structs in events with experimental ABIEncoderV2. This used to log wrong values.\n * Type Checker: Report error when using structs in events without experimental ABIEncoderV2. This used to crash or log the wrong values.\n * Parser: Consider all unicode line terminators (LF, VF, FF, CR, NEL, LS, PS) for single-line comments\n and string literals. They are invalid in strings and will end comments.\n * Parser: Disallow unterminated multi-line comments at the end of input.\n * Parser: Treat ``/** /`` as unterminated multi-line comment.\n\n### 0.4.24 (2018-05-16)\n\nLanguage Features:\n * Code Generator: Use native shift instructions on target Constantinople.\n * General: Allow multiple variables to be declared as part of a tuple assignment, e.g. ``(uint a, uint b) = ...``.\n * General: Remove deprecated ``constant`` as function state modifier from documentation and tests (but still leave it as a valid feature).\n * Type Checker: Deprecate the ``years`` unit denomination and raise a warning for it (or an error as experimental 0.5.0 feature).\n * Type Checker: Make literals (without explicit type casting) an error for tight packing as experimental 0.5.0 feature.\n * Type Checker: Warn about wildcard tuple assignments (this will turn into an error with version 0.5.0).\n * Type Checker: Warn when ``keccak256``, ``sha256`` and ``ripemd160`` are not used with a single bytes argument (suggest to use ``abi.encodePacked(...)``). This will turn into an error with version 0.5.0.\n\nCompiler Features:\n * Build System: Update internal dependency of jsoncpp to 1.8.4, which introduces more strictness and reduces memory usage.\n * Control Flow Graph: Add Control Flow Graph as analysis structure.\n * Control Flow Graph: Warn about returning uninitialized storage pointers.\n * Gas Estimator: Only explore paths with higher gas costs. This reduces accuracy but greatly improves the speed of gas estimation.\n * Optimizer: Remove unnecessary masking of the result of known short instructions (``ADDRESS``, ``CALLER``, ``ORIGIN`` and ``COINBASE``).\n * Parser: Display nicer error messages by showing the actual tokens and not internal names.\n * Parser: Use the entire location of the token instead of only its starting position as source location for parser errors.\n * SMT Checker: Support state variables of integer and bool type.\n\nBugfixes:\n * Code Generator: Fix ``revert`` with reason coming from a state or local string variable.\n * Type Checker: Show proper error when trying to ``emit`` a non-event.\n * Type Checker: Warn about empty tuple components (this will turn into an error with version 0.5.0).\n * Type Checker: The ABI encoding functions are pure and thus can be used for constants.\n\n### 0.4.23 (2018-04-19)\n\nFeatures:\n * Build system: Support Ubuntu Bionic.\n * SMTChecker: Integration with CVC4 SMT solver\n * Syntax Checker: Warn about functions named \"constructor\".\n\nBugfixes:\n * Type Checker: Improve error message for failed function overload resolution.\n * Type Checker: Do not complain about new-style constructor and fallback function to have the same name.\n * Type Checker: Detect multiple constructor declarations in the new syntax and old syntax.\n * Type Checker: Explicit conversion of ``bytesXX`` to ``contract`` is properly disallowed.\n\n### 0.4.22 (2018-04-16)\n\nFeatures:\n * Code Generator: Initialize arrays without using ``msize()``.\n * Code Generator: More specialized and thus optimized implementation for ``x.push(...)``\n * Commandline interface: Error when missing or inaccessible file detected. Suppress it with the ``--ignore-missing`` flag.\n * Constant Evaluator: Fix evaluation of single element tuples.\n * General: Add encoding routines ``abi.encodePacked``, ``abi.encode``, ``abi.encodeWithSelector`` and ``abi.encodeWithSignature``.\n * General: Add global function ``gasleft()`` and deprecate ``msg.gas``.\n * General: Add global function ``blockhash(uint)`` and deprecate ``block.hash(uint)``.\n * General: Allow providing reason string for ``revert()`` and ``require()``.\n * General: Introduce new constructor syntax using the ``constructor`` keyword as experimental 0.5.0 feature.\n * General: Limit the number of errors output in a single run to 256.\n * General: Support accessing dynamic return data in post-byzantium EVMs.\n * General: Allow underscores in numeric and hex literals to separate thousands and quads.\n * Inheritance: Error when using empty parentheses for base class constructors that require arguments as experimental 0.5.0 feature.\n * Inheritance: Error when using no parentheses in modifier-style constructor calls as experimental 0.5.0 feature.\n * Interfaces: Allow overriding external functions in interfaces with public in an implementing contract.\n * Optimizer: Optimize ``SHL`` and ``SHR`` only involving constants (Constantinople only).\n * Optimizer: Remove useless ``SWAP1`` instruction preceding a commutative instruction (such as ``ADD``, ``MUL``, etc).\n * Optimizer: Replace comparison operators (``LT``, ``GT``, etc) with opposites if preceded by ``SWAP1``, e.g. ``SWAP1 LT`` is replaced with ``GT``.\n * Optimizer: Optimize across ``mload`` if ``msize()`` is not used.\n * Static Analyzer: Error on duplicated super constructor calls as experimental 0.5.0 feature.\n * Syntax Checker: Issue warning for empty structs (or error as experimental 0.5.0 feature).\n * Syntax Checker: Warn about modifiers on functions without implementation (this will turn into an error with version 0.5.0).\n * Syntax Tests: Add source locations to syntax test expectations.\n * Type Checker: Improve documentation and warnings for accessing contract members inherited from ``address``.\n\nBugfixes:\n * Code Generator: Allow ``block.blockhash`` without being called.\n * Code Generator: Do not include internal functions in the runtime bytecode which are only referenced in the constructor.\n * Code Generator: Properly skip unneeded storage array cleanup when not reducing length.\n * Code Generator: Bugfix in modifier lookup in libraries.\n * Code Generator: Implement packed encoding of external function types.\n * Code Generator: Treat empty base constructor argument list as not provided.\n * Code Generator: Properly force-clean bytesXX types for shortening conversions.\n * Commandline interface: Fix error messages for imported files that do not exist.\n * Commandline interface: Support ``--evm-version constantinople`` properly.\n * DocString Parser: Fix error message for empty descriptions.\n * Gas Estimator: Correctly ignore costs of fallback function for other functions.\n * JSON AST: Remove storage qualifier for type name strings.\n * Parser: Fix internal compiler error when parsing ``var`` declaration without identifier.\n * Parser: Fix parsing of getters for function type variables.\n * Standard JSON: Support ``constantinople`` as ``evmVersion`` properly.\n * Static Analyzer: Fix non-deterministic order of unused variable warnings.\n * Static Analyzer: Invalid arithmetic with constant expressions causes errors.\n * Type Checker: Fix detection of recursive structs.\n * Type Checker: Fix asymmetry bug when comparing with literal numbers.\n * Type System: Improve error message when attempting to shift by a fractional amount.\n * Type System: Make external library functions accessible.\n * Type System: Prevent encoding of weird types.\n * Type System: Restrict rational numbers to 4096 bits.\n\n### 0.4.21 (2018-03-07)\n\nFeatures:\n * Code Generator: Assert that ``k != 0`` for ``mulmod(a, b, k)`` and ``addmod(a, b, k)`` as experimental 0.5.0 feature.\n * Code Generator: Do not retain any gas in calls (except if EVM version is set to homestead).\n * Code Generator: Use ``STATICCALL`` opcode for calling ``view`` and ``pure`` functions as experimental 0.5.0 feature.\n * General: C99/C++-style scoping rules (instead of JavaScript function scoping) take effect as experimental v0.5.0 feature.\n * General: Improved messaging when error spans multiple lines of a sourcefile\n * General: Support and recommend using ``emit EventName();`` to call events explicitly.\n * Inline Assembly: Enforce strict mode as experimental 0.5.0 feature.\n * Interface: Provide ability to select target EVM version (homestead or byzantium, with byzantium being the default).\n * Standard JSON: Reject badly formatted invalid JSON inputs.\n * Type Checker: Disallow uninitialized storage pointers as experimental 0.5.0 feature.\n * Syntax Analyser: Do not warn about experimental features if they do not concern code generation.\n * Syntax Analyser: Do not warn about ``pragma experimental \"v0.5.0\"`` and do not set the experimental flag in the bytecode for this.\n * Syntax Checker: Mark ``throw`` as an error as experimental 0.5.0 feature.\n * Syntax Checker: Issue error if no visibility is specified on contract functions as experimental 0.5.0 feature.\n * Syntax Checker: Issue warning when using overloads of ``address`` on contract instances.\n * Type Checker: disallow combining hex numbers and unit denominations as experimental 0.5.0 feature.\n\nBugfixes:\n * Assembly: Raise error on oversized number literals in assembly.\n * JSON-AST: Add \"documentation\" property to function, event and modifier definition.\n * Resolver: Properly determine shadowing for imports with aliases.\n * Standalone Assembly: Do not ignore input after closing brace of top level block.\n * Standard JSON: Catch errors properly when invalid \"sources\" are passed.\n * Standard JSON: Ensure that library addresses supplied are of correct length and hex prefixed.\n * Type Checker: Properly detect which array and struct types are unsupported by the old ABI encoder.\n * Type Checker: Properly warn when using ``_offset`` and ``_slot`` for constants in inline assembly.\n * Commandline interface: throw error if option is unknown\n\n### 0.4.20 (2018-02-14)\n\nFeatures:\n * Code Generator: Prevent non-view functions in libraries from being called\n directly (as opposed to via delegatecall).\n * Commandline interface: Support strict mode of assembly (disallowing jumps,\n instructional opcodes, etc) with the ``--strict-assembly`` switch.\n * Inline Assembly: Issue warning for using jump labels (already existed for jump instructions).\n * Inline Assembly: Support some restricted tokens (return, byte, address) as identifiers in Iulia mode.\n * Optimiser: Replace ``x % 2**i`` by ``x & (2**i-1)``.\n * Resolver: Continue resolving references after the first error.\n * Resolver: Suggest alternative identifiers if a given identifier is not found.\n * SMT Checker: Take if-else branch conditions into account in the SMT encoding of the program\n variables.\n * Syntax Checker: Deprecate the ``var`` keyword (and mark it an error as experimental 0.5.0 feature).\n * Type Checker: Allow `this.f.selector` to be a pure expression.\n * Type Checker: Issue warning for using ``public`` visibility for interface functions.\n * Type Checker: Limit the number of warnings raised for creating abstract contracts.\n\nBugfixes:\n * Error Output: Truncate huge number literals in the middle to avoid output blow-up.\n * Parser: Disallow event declarations with no parameter list.\n * Standard JSON: Populate the ``sourceLocation`` field in the error list.\n * Standard JSON: Properly support contract and library file names containing a colon (such as URLs).\n * Type Checker: Suggest the experimental ABI encoder if using ``struct``s as function parameters\n (instead of an internal compiler error).\n * Type Checker: Improve error message for wrong struct initialization.\n\n### 0.4.19 (2017-11-30)\n\nFeatures:\n * Code Generator: New ABI decoder which supports structs and arbitrarily nested\n arrays and checks input size (activate using ``pragma experimental ABIEncoderV2;``).\n * General: Allow constant variables to be used as array length.\n * Inline Assembly: ``if`` statement.\n * Standard JSON: Support the ``outputSelection`` field for selective compilation of target artifacts.\n * Syntax Checker: Turn the usage of ``callcode`` into an error as experimental 0.5.0 feature.\n * Type Checker: Improve address checksum warning.\n * Type Checker: More detailed errors for invalid array lengths (such as division by zero).\n\nBugfixes:\n\n### 0.4.18 (2017-10-18)\n\nFeatures:\n * Code Generator: Always use all available gas for calls as experimental 0.5.0 feature\n (previously, some amount was retained in order to work in pre-Tangerine-Whistle\n EVM versions)\n * Parser: Better error message for unexpected trailing comma in parameter lists.\n * Standard JSON: Support the ``outputSelection`` field for selective compilation of supplied sources.\n * Syntax Checker: Unary ``+`` is now a syntax error as experimental 0.5.0 feature.\n * Type Checker: Disallow non-pure constant state variables as experimental 0.5.0 feature.\n * Type Checker: Do not add members of ``address`` to contracts as experimental 0.5.0 feature.\n * Type Checker: Force interface functions to be external as experimental 0.5.0 feature.\n * Type Checker: Require ``storage`` or ``memory`` keyword for local variables as experimental 0.5.0 feature.\n * Compiler Interface: Better formatted error message for long source snippets\n\nBugfixes:\n * Code Generator: Allocate one byte per memory byte array element instead of 32.\n * Code Generator: Do not accept data with less than four bytes (truncated function\n signature) for regular function calls - fallback function is invoked instead.\n * Optimizer: Remove unused stack computation results.\n * Parser: Fix source location of VariableDeclarationStatement.\n * Type Checker: Allow ``gas`` in view functions.\n * Type Checker: Do not mark event parameters as shadowing state variables.\n * Type Checker: Prevent duplicate event declarations.\n * Type Checker: Properly check array length and don't rely on an assertion in code generation.\n * Type Checker: Properly support overwriting members inherited from ``address`` in a contract\n (such as ``balance``, ``transfer``, etc.)\n * Type Checker: Validate each number literal in tuple expressions even if they are not assigned from.\n\n### 0.4.17 (2017-09-21)\n\nFeatures:\n * Assembly Parser: Support multiple assignment (``x, y := f()``).\n * Code Generator: Keep a single copy of encoding functions when using the experimental \"ABIEncoderV2\".\n * Code Generator: Partial support for passing ``structs`` as arguments and return parameters (requires ``pragma experimental ABIEncoderV2;`` for now).\n * General: Support ``pragma experimental \"v0.5.0\";`` to activate upcoming breaking changes.\n * General: Added ``.selector`` member on external function types to retrieve their signature.\n * Optimizer: Add new optimization step to remove unused ``JUMPDEST``s.\n * Static Analyzer: Warn when using deprecated builtins ``sha3`` and ``suicide``\n (replaced by ``keccak256`` and ``selfdestruct``, introduced in 0.4.2 and 0.2.0, respectively).\n * Syntax Checker: Warn if no visibility is specified on contract functions.\n * Type Checker: Display helpful warning for unused function arguments/return parameters.\n * Type Checker: Do not show the same error multiple times for events.\n * Type Checker: Greatly reduce the number of duplicate errors shown for duplicate constructors and functions.\n * Type Checker: Warn on using literals as tight packing parameters in ``keccak256``, ``sha3``, ``sha256`` and ``ripemd160``.\n * Type Checker: Enforce ``view`` and ``pure``.\n * Type Checker: Enforce ``view`` / ``constant`` with error as experimental 0.5.0 feature.\n * Type Checker: Enforce fallback functions to be ``external`` as experimental 0.5.0 feature.\n\nBugfixes:\n * ABI JSON: Include all overloaded events.\n * Parser: Crash fix related to parseTypeName.\n * Type Checker: Allow constant byte arrays.\n\n### 0.4.16 (2017-08-24)\n\nFeatures:\n * ABI JSON: Include new field ``stateMutability`` with values ``pure``, ``view``,\n ``nonpayable`` and ``payable``.\n * Analyzer: Experimental partial support for Z3 SMT checker (\"SMTChecker\").\n * Build System: Shared libraries (``libsolutil``, ``libevmasm``, ``libsolidity``\n and ``liblll``) are no longer produced during the build process.\n * Code generator: Experimental new implementation of ABI encoder that can\n encode arbitrarily nested arrays (\"ABIEncoderV2\")\n * Metadata: Store experimental flag in metadata CBOR.\n * Parser: Display previous visibility specifier in error if multiple are found.\n * Parser: Introduce ``pure`` and ``view`` keyword for functions,\n ``constant`` remains an alias for ``view`` and pureness is not enforced yet,\n so use with care.\n * Static Analyzer: Warn about large storage structures.\n * Syntax Checker: Support ``pragma experimental ;`` to turn on\n experimental features.\n * Type Checker: More detailed error message for invalid overrides.\n * Type Checker: Warn about shifting a literal.\n\nBugfixes:\n * Assembly Parser: Be more strict about number literals.\n * Assembly Parser: Limit maximum recursion depth.\n * Parser: Enforce commas between array and tuple elements.\n * Parser: Limit maximum recursion depth.\n * Type Checker: Crash fix related to ``using``.\n * Type Checker: Disallow constructors in libraries.\n * Type Checker: Reject the creation of interface contracts using the ``new`` statement.\n\n### 0.4.15 (2017-08-08)\n\nFeatures:\n * Type Checker: Show unimplemented function if trying to instantiate an abstract class.\n\nBugfixes:\n * Code Generator: ``.delegatecall()`` should always return execution outcome.\n * Code Generator: Provide \"new account gas\" for low-level ``callcode`` and ``delegatecall``.\n * Type Checker: Constructors must be implemented if declared.\n * Type Checker: Disallow the ``.gas()`` modifier on ``ecrecover``, ``sha256`` and ``ripemd160``.\n * Type Checker: Do not mark overloaded functions as shadowing other functions.\n * Type Checker: Internal library functions must be implemented if declared.\n\n### 0.4.14 (2017-07-31)\n\nFeatures:\n * C API (``jsonCompiler``): Export the ``license`` method.\n * Code Generator: Optimise the fallback function, by removing a useless jump.\n * Inline Assembly: Show useful error message if trying to access calldata variables.\n * Inline Assembly: Support variable declaration without initial value (defaults to 0).\n * Metadata: Only include files which were used to compile the given contract.\n * Type Checker: Disallow value transfers to contracts without a payable fallback function.\n * Type Checker: Include types in explicit conversion error message.\n * Type Checker: Raise proper error for arrays too large for ABI encoding.\n * Type checker: Warn if using ``this`` in a constructor.\n * Type checker: Warn when existing symbols, including builtins, are overwritten.\n\nBugfixes:\n * Code Generator: Properly clear return memory area for ecrecover.\n * Type Checker: Fix crash for some assignment to non-lvalue.\n * Type Checker: Fix invalid \"specify storage keyword\" warning for reference members of structs.\n * Type Checker: Mark modifiers as internal.\n * Type Checker: Re-allow multiple mentions of the same modifier per function.\n\n\n### 0.4.13 (2017-07-06)\n\nFeatures:\n * Syntax Checker: Deprecated \"throw\" in favour of require(), assert() and revert().\n * Type Checker: Warn if a local storage reference variable does not explicitly use the keyword ``storage``.\n\nBugfixes:\n * Code Generator: Correctly unregister modifier variables.\n * Compiler Interface: Only output AST if analysis was successful.\n * Error Output: Do not omit the error type.\n\n### 0.4.12 (2017-07-03)\n\nFeatures:\n * Assembly: Add ``CREATE2`` (EIP86), ``STATICCALL`` (EIP214), ``RETURNDATASIZE`` and ``RETURNDATACOPY`` (EIP211) instructions.\n * Assembly: Display auxiliary data in the assembly output.\n * Assembly: Renamed ``SHA3`` to ``KECCAK256``.\n * AST: export all attributes to JSON format.\n * C API (``jsonCompiler``): Use the Standard JSON I/O internally.\n * Code Generator: Added the Whiskers template system.\n * Inline Assembly: ``for`` and ``switch`` statements.\n * Inline Assembly: Function definitions and function calls.\n * Inline Assembly: Introduce ``keccak256`` as an opcode. ``sha3`` is still a valid alias.\n * Inline Assembly: Present proper error message when not supplying enough arguments to a functional\n instruction.\n * Inline Assembly: Warn when instructions shadow Solidity variables.\n * Inline Assembly: Warn when using ``jump``s.\n * Remove obsolete Why3 output.\n * Type Checker: Enforce strict UTF-8 validation.\n * Type Checker: Warn about copies in storage that might overwrite unexpectedly.\n * Type Checker: Warn about type inference from literal numbers.\n * Static Analyzer: Warn about deprecation of ``callcode``.\n\nBugfixes:\n * Assembly: mark ``MLOAD`` to have side effects in the optimiser.\n * Code Generator: Fix ABI encoding of empty literal string.\n * Code Generator: Fix negative stack size checks.\n * Code generator: Use ``REVERT`` instead of ``INVALID`` for generated input validation routines.\n * Inline Assembly: Enforce function arguments when parsing functional instructions.\n * Optimizer: Disallow optimizations involving ``MLOAD`` because it changes ``MSIZE``.\n * Static Analyzer: Unused variable warnings no longer issued for variables used inside inline assembly.\n * Type Checker: Fix address literals not being treated as compile-time constants.\n * Type Checker: Fixed crash concerning non-callable types.\n * Type Checker: Fixed segfault with constant function parameters\n * Type Checker: Disallow comparisons between mapping and non-internal function types.\n * Type Checker: Disallow invoking the same modifier multiple times.\n * Type Checker: Do not treat strings that look like addresses as addresses.\n * Type Checker: Support valid, but incorrectly rejected UTF-8 sequences.\n\n### 0.4.11 (2017-05-03)\n\nFeatures:\n * Implement the Standard JSON Input / Output API\n * Support ``interface`` contracts.\n * C API (``jsonCompiler``): Add the ``compileStandard()`` method to process a Standard JSON I/O.\n * Commandline interface: Add the ``--standard-json`` parameter to process a Standard JSON I/O.\n * Commandline interface: Support ``--allow-paths`` to define trusted import paths. Note: the\n path(s) of the supplied source file(s) is always trusted.\n * Inline Assembly: Storage variable access using ``_slot`` and ``_offset`` suffixes.\n * Inline Assembly: Disallow blocks with unbalanced stack.\n * Static analyzer: Warn about statements without effects.\n * Static analyzer: Warn about unused local variables, parameters, and return parameters.\n * Syntax checker: issue deprecation warning for unary '+'\n\nBugfixes:\n * Assembly output: Implement missing AssemblyItem types.\n * Compiler interface: Fix a bug where source indexes could be inconsistent between Solidity compiled\n with different compilers (clang vs. gcc) or compiler settings. The bug was visible in AST\n and source mappings.\n * Gas Estimator: Reflect the most recent fee schedule.\n * Type system: Contract inheriting from base with unimplemented constructor should be abstract.\n * Optimizer: Number representation bug in the constant optimizer fixed.\n\n### 0.4.10 (2017-03-15)\n\nFeatures:\n * Add ``assert(condition)``, which throws if condition is false (meant for internal errors).\n * Add ``require(condition)``, which throws if condition is false (meant for invalid input).\n * Commandline interface: Do not overwrite files unless forced.\n * Introduce ``.transfer(value)`` for sending Ether.\n * Code generator: Support ``revert()`` to abort with rolling back, but not consuming all gas.\n * Inline assembly: Support ``revert`` (EIP140) as an opcode.\n * Parser: Support scientific notation in numbers (e.g. ``2e8`` and ``200e-2``).\n * Type system: Support explicit conversion of external function to address.\n * Type system: Warn if base of exponentiation is literal (result type might be unexpected).\n * Type system: Warn if constant state variables are not compile-time constants.\n\nBugfixes:\n * Commandline interface: Always escape filenames (replace ``/``, ``:`` and ``.`` with ``_``).\n * Commandline interface: Do not try creating paths ``.`` and ``..``.\n * Commandline interface: Allow long library names.\n * Parser: Disallow octal literals.\n * Type system: Fix a crash caused by continuing on fatal errors in the code.\n * Type system: Disallow compound assignment for tuples.\n * Type system: Detect cyclic dependencies between constants.\n * Type system: Disallow arrays with negative length.\n * Type system: Fix a crash related to invalid binary operators.\n * Type system: Disallow ``var`` declaration with empty tuple type.\n * Type system: Correctly convert function argument types to pointers for member functions.\n * Type system: Move privateness of constructor into AST itself.\n * Inline assembly: Charge one stack slot for non-value types during analysis.\n * Assembly output: Print source location before the operation it refers to instead of after.\n * Optimizer: Stop trying to optimize tricky constants after a while.\n\n### 0.4.9 (2017-01-31)\n\nFeatures:\n * Compiler interface: Contracts and libraries can be referenced with a ``file:`` prefix to make them unique.\n * Compiler interface: Report source location for \"stack too deep\" errors.\n * AST: Use deterministic node identifiers.\n * Inline assembly: introduce ``invalid`` (EIP141) as an opcode.\n * Type system: Introduce type identifier strings.\n * Type checker: Warn about invalid checksum for addresses and deduce type from valid ones.\n * Metadata: Do not include platform in the version number.\n * Metadata: Add option to store sources as literal content.\n * Code generator: Extract array utils into low-level functions.\n * Code generator: Internal errors (array out of bounds, etc.) now cause a reversion by using an invalid\n instruction (0xfe - EIP141) instead of an invalid jump. Invalid jump is still kept for explicit throws.\n\nBugfixes:\n * Code generator: Allow recursive structs.\n * Inline assembly: Disallow variables named like opcodes.\n * Type checker: Allow multiple events of the same name (but with different arities or argument types)\n * Natspec parser: Fix error with ``@param`` parsing and whitespace.\n\n### 0.4.8 (2017-01-13)\n\nFeatures:\n * Optimiser: Performance improvements.\n * Output: Print assembly in new standardized Solidity assembly format.\n\nBugfixes:\n * Remappings: Prefer longer context over longer prefix.\n * Type checker, code generator: enable access to events of base contracts' names.\n * Imports: ``import \".dir/a\"`` is not a relative path. Relative paths begin with directory ``.`` or ``..``.\n * Type checker, disallow inheritances of different kinds (e.g. a function and a modifier) of members of the same name\n\n### 0.4.7 (2016-12-15)\n\nFeatures:\n * Bitshift operators.\n * Type checker: Warn when ``msg.value`` is used in non-payable function.\n * Code generator: Inject the Swarm hash of a metadata file into the bytecode.\n * Code generator: Replace expensive memcpy precompile by simple assembly loop.\n * Optimizer: Some dead code elimination.\n\nBugfixes:\n * Code generator: throw if calling the identity precompile failed during memory (array) copying.\n * Type checker: string literals that are not valid UTF-8 cannot be converted to string type\n * Code generator: any non-zero value given as a boolean argument is now converted into 1.\n * AST Json Converter: replace ``VariableDefinitionStatement`` nodes with ``VariableDeclarationStatement``\n * AST Json Converter: fix the camel case in ``ElementaryTypeNameExpression``\n * AST Json Converter: replace ``public`` field with ``visibility`` in the function definition nodes\n\n### 0.4.6 (2016-11-22)\n\nBugfixes:\n * Optimizer: Knowledge about state was not correctly cleared for JUMPDESTs (introduced in 0.4.5)\n\n### 0.4.5 (2016-11-21)\n\nFeatures:\n * Function types\n * Do-while loops: support for a ``do while ();`` control structure\n * Inline assembly: support ``invalidJumpLabel`` as a jump label.\n * Type checker: now more eagerly searches for a common type of an inline array with mixed types\n * Code generator: generates a runtime error when an out-of-range value is converted into an enum type.\n\nBugfixes:\n\n * Inline assembly: calculate stack height warning correctly even when local variables are used.\n * Code generator: check for value transfer in non-payable constructors.\n * Parser: disallow empty enum definitions.\n * Type checker: disallow conversion between different enum types.\n * Interface JSON: do not include trailing new line.\n\n### 0.4.4 (2016-10-31)\n\nBugfixes:\n * Type checker: forbid signed exponential that led to an incorrect use of EXP opcode.\n * Code generator: properly clean higher order bytes before storing in storage.\n\n### 0.4.3 (2016-10-25)\n\nFeatures:\n\n * Inline assembly: support both ``suicide`` and ``selfdestruct`` opcodes\n (note: ``suicide`` is deprecated).\n * Inline assembly: issue warning if stack is not balanced after block.\n * Include ``keccak256()`` as an alias to ``sha3()``.\n * Support shifting constant numbers.\n\nBugfixes:\n * Commandline interface: Disallow unknown options in ``solc``.\n * Name resolver: Allow inheritance of ``enum`` definitions.\n * Type checker: Proper type checking for bound functions.\n * Type checker: fixed crash related to invalid fixed point constants\n * Type checker: fixed crash related to invalid literal numbers.\n * Type checker: ``super.x`` does not look up ``x`` in the current contract.\n * Code generator: expect zero stack increase after ``super`` as an expression.\n * Code generator: fix an internal compiler error for ``L.Foo`` for ``enum Foo`` defined in library ``L``.\n * Code generator: allow inheritance of ``enum`` definitions.\n * Inline assembly: support the ``address`` opcode.\n * Inline assembly: fix parsing of assignment after a label.\n * Inline assembly: external variables of unsupported type (such as ``this``, ``super``, etc.)\n are properly detected as unusable.\n * Inline assembly: support variables within modifiers.\n * Optimizer: fix related to stale knowledge about SHA3 operations\n\n### 0.4.2 (2016-09-17)\n\nBugfixes:\n\n * Code Generator: Fix library functions being called from payable functions.\n * Type Checker: Fixed a crash about invalid array types.\n * Code Generator: Fixed a call gas bug that became visible after\n version 0.4.0 for calls where the output is larger than the input.\n\n### 0.4.1 (2016-09-09)\n\n * Build System: Fixes to allow library compilation.\n\n### 0.4.0 (2016-09-08)\n\nThis release deliberately breaks backwards compatibility mostly to\nenforce some safety features. The most important change is that you have\nto explicitly specify if functions can receive ether via the ``payable``\nmodifier. Furthermore, more situations cause exceptions to be thrown.\n\nMinimal changes to be made for upgrade:\n - Add ``payable`` to all functions that want to receive Ether\n (including the constructor and the fallback function).\n - Change ``_`` to ``_;`` in modifiers.\n - Add version pragma to each file: ``pragma solidity ^0.4.0;``\n\nBreaking Changes:\n\n * Source files have to specify the compiler version they are\n compatible with using e.g. ``pragma solidity ^0.4.0;`` or\n ``pragma solidity >=0.4.0 <0.4.8;``\n * Functions that want to receive Ether have to specify the\n new ``payable`` modifier (otherwise they throw).\n * Contracts that want to receive Ether with a plain \"send\"\n have to implement a fallback function with the ``payable``\n modifier. Contracts now throw if no payable fallback\n function is defined and no function matches the signature.\n * Failing contract creation through \"new\" throws.\n * Division / modulus by zero throws.\n * Function call throws if target contract does not have code\n * Modifiers are required to contain ``_`` (use ``if (false) _`` as a workaround if needed).\n * Modifiers: return does not skip part in modifier after ``_``.\n * Placeholder statement `_` in modifier now requires explicit `;`.\n * ``ecrecover`` now returns zero if the input is malformed (it previously returned garbage).\n * The ``constant`` keyword cannot be used for constructors or the fallback function.\n * Removed ``--interface`` (Solidity interface) output option\n * JSON AST: General cleanup, renamed many nodes to match their C++ names.\n * JSON output: ``srcmap-runtime`` renamed to ``srcmapRuntime``.\n * Moved (and reworked) standard library contracts from inside the compiler to github.com/ethereum/solidity/std\n (``import \"std\";`` or ``import owned;`` do not work anymore).\n * Confusing and undocumented keyword ``after`` was removed.\n * New reserved words: ``abstract``, ``hex``, ``interface``, ``payable``, ``pure``, ``static``, ``view``.\n\nFeatures:\n\n * Hexadecimal string literals: ``hex\"ab1248fe\"``\n * Internal: Inline assembly usable by the code generator.\n * Commandline interface: Using ``-`` as filename allows reading from stdin.\n * Interface JSON: Fallback function is now part of the ABI.\n * Interface: Version string now *SemVer* compatible.\n * Code generator: Do not provide \"new account gas\" if we know the called account exists.\n\nBugfixes:\n\n * JSON AST: Nodes were added at wrong parent\n * Why3 translator: Crash fix for exponentiation\n * Commandline Interface: linking libraries with underscores in their name.\n * Type Checker: Fallback function cannot return data anymore.\n * Code Generator: Fix crash when ``sha3()`` was used on unsupported types.\n * Code Generator: Manually set gas stipend for ``.send(0)``.\n\nLots of changes to the documentation mainly by voluntary external contributors.\n\n### 0.3.6 (2016-08-10)\n\nFeatures:\n\n * Formal verification: Take external effects on a contract into account.\n * Type Checker: Warning about unused return value of low-level calls and send.\n * Output: Source location and node id as part of AST output\n * Output: Source location mappings for bytecode\n * Output: Formal verification as part of json compiler output.\n\nBugfixes:\n\n * Commandline Interface: Do not crash if input is taken from stdin.\n * Scanner: Correctly support unicode escape codes in strings.\n * JSON output: Fix error about relative / absolute source file names.\n * JSON output: Fix error about invalid utf8 strings.\n * Code Generator: Dynamic allocation of empty array caused infinite loop.\n * Code Generator: Correctly calculate gas requirements for memcpy precompile.\n * Optimizer: Clear known state if two code paths are joined.\n\n### 0.3.5 (2016-06-10)\n\nFeatures:\n\n * Context-dependent path remappings (different modules can use the same library in different versions)\n\nBugfixes:\n\n * Type Checking: Dynamic return types were removed when fetching data from external calls, now they are replaced by an \"unusable\" type.\n * Type Checking: Overrides by constructors were considered making a function non-abstract.\n\n### 0.3.4 (2016-05-31)\n\nNo change outside documentation.\n\n### 0.3.3 (2016-05-27)\n\n * Allow internal library functions to be called (by \"inlining\")\n * Fractional/rational constants (only usable with fixed point types, which are still in progress)\n * Inline assembly has access to internal functions (as jump labels)\n * Running `solc` without arguments on a terminal will print help.\n * Bugfix: Remove some non-determinism in code generation.\n * Bugfix: Corrected usage of not / bnot / iszero in inline assembly\n * Bugfix: Correctly clean bytesNN types before comparison\n\n### 0.3.2 (2016-04-18)\n\n * Bugfix: Inline assembly parser: `byte` opcode was unusable\n * Bugfix: Error reporting: tokens for variably-sized types were not converted to string properly\n * Bugfix: Dynamic arrays of structs were not deleted correctly.\n * Bugfix: Static arrays in constructor parameter list were not decoded correctly.\n\n### 0.3.1 (2016-03-31)\n\n * Inline assembly\n * Bugfix: Code generation: array access with narrow types did not clean higher order bits\n * Bugfix: Error reporting: error reporting with unknown source location caused a crash\n\n### 0.3.0 (2016-03-11)\n\nBREAKING CHANGES:\n\n * Added new keywords `assembly`, `foreign`, `fixed`, `ufixed`, `fixedNxM`, `ufixedNxM` (for various values of M and N), `timestamp`\n * Number constant division does not round to integer, but to a fixed point type (e.g. `1 / 2 != 1`, but `1 / 2 == 0.5`).\n * Library calls now default to use DELEGATECALL (e.g. called library functions see the same value as the calling function for `msg.value` and `msg.sender`).\n * `
.delegatecall` as a low-level calling interface\n\nBugfixes:\n * Fixed a bug in the optimizer that resulted in comparisons being wrong.\n\n\n### 0.2.2 (2016-02-17)\n\n * Index access for types `bytes1`, ..., `bytes32` (only read access for now).\n * Bugfix: Type checker crash for wrong number of base constructor parameters.\n\n### 0.2.1 (2016-01-30)\n\n * Inline arrays, i.e. `var y = [1,x,f()];` if there is a common type for `1`, `x` and `f()`. Note that the result is always a fixed-length memory array and conversion to dynamic-length memory arrays is not yet possible.\n * Import similar to ECMAScript6 import (`import \"abc.sol\" as d` and `import {x, y} from \"abc.sol\"`).\n * Commandline compiler solc automatically resolves missing imports and allows for \"include directories\".\n * Conditional: `x ? y : z`\n * Bugfix: Fixed several bugs where the optimizer generated invalid code.\n * Bugfix: Enums and structs were not accessible to other contracts.\n * Bugfix: Fixed segfault connected to function parameter types, appeared during gas estimation.\n * Bugfix: Type checker crash for wrong number of base constructor parameters.\n * Bugfix: Allow function overloads with different array types.\n * Bugfix: Allow assignments of type `(x) = 7`.\n * Bugfix: Type `uint176` was not available.\n * Bugfix: Fixed crash during type checking concerning constructor calls.\n * Bugfix: Fixed crash during code generation concerning invalid accessors for struct types.\n * Bugfix: Fixed crash during code generating concerning computing a hash of a struct type.\n\n### 0.2.0 (2015-12-02)\n\n * **Breaking Change**: `new ContractName.value(10)()` has to be written as `(new ContractName).value(10)()`\n * Added `selfdestruct` as an alias for `suicide`.\n * Allocation of memory arrays using `new`.\n * Binding library functions to types via `using x for y`\n * `addmod` and `mulmod` (modular addition and modular multiplication with arbitrary intermediate precision)\n * Bugfix: Constructor arguments of fixed array type were not read correctly.\n * Bugfix: Memory allocation of structs containing arrays or strings.\n * Bugfix: Data location for explicit memory parameters in libraries was set to storage.\n\n### 0.1.7 (2015-11-17)\n\n * Improved error messages for unexpected tokens.\n * Proof-of-concept transcompilation to why3 for formal verification of contracts.\n * Bugfix: Arrays (also strings) as indexed parameters of events.\n * Bugfix: Writing to elements of `bytes` or `string` overwrite others.\n * Bugfix: \"Successor block not found\" on Windows.\n * Bugfix: Using string literals in tuples.\n * Bugfix: Cope with invalid commit hash in version for libraries.\n * Bugfix: Some test framework fixes on windows.\n\n### 0.1.6 (2015-10-16)\n\n * `.push()` for dynamic storage arrays.\n * Tuple expressions (`(1,2,3)` or `return (1,2,3);`)\n * Declaration and assignment of multiple variables (`var (x,y,) = (1,2,3,4,5);` or `var (x,y) = f();`)\n * Destructuring assignment (`(x,y,) = (1,2,3)`)\n * Bugfix: Internal error about usage of library function with invalid types.\n * Bugfix: Correctly parse `Library.structType a` at statement level.\n * Bugfix: Correctly report source locations of parenthesized expressions (as part of \"tuple\" story).\n\n### 0.1.5 (2015-10-07)\n\n * Breaking change in storage encoding: Encode short byte arrays and strings together with their length in storage.\n * Report warnings\n * Allow storage reference types for public library functions.\n * Access to types declared in other contracts and libraries via `.`.\n * Version stamp at beginning of runtime bytecode of libraries.\n * Bugfix: Problem with initialized string state variables and dynamic data in constructor.\n * Bugfix: Resolve dependencies concerning `new` automatically.\n * Bugfix: Allow four indexed arguments for anonymous events.\n * Bugfix: Detect too large integer constants in functions that accept arbitrary parameters.\n\n### 0.1.4 (2015-09-30)\n\n * Bugfix: Returning fixed-size arrays.\n * Bugfix: combined-json output of solc.\n * Bugfix: Accessing fixed-size array return values.\n * Bugfix: Disallow assignment from literal strings to storage pointers.\n * Refactoring: Move type checking into its own module.\n\n### 0.1.3 (2015-09-25)\n\n * `throw` statement.\n * Libraries that contain functions which are called via CALLCODE.\n * Linker stage for compiler to insert other contract's addresses (used for libraries).\n * Compiler option to output runtime part of contracts.\n * Compile-time out of bounds check for access to fixed-size arrays by integer constants.\n * Version string includes libevmasm/libethereum's version (contains the optimizer).\n * Bugfix: Accessors for constant public state variables.\n * Bugfix: Propagate exceptions in clone contracts.\n * Bugfix: Empty single-line comments are now treated properly.\n * Bugfix: Properly check the number of indexed arguments for events.\n * Bugfix: Strings in struct constructors.\n\n### 0.1.2 (2015-08-20)\n\n * Improved commandline interface.\n * Explicit conversion between `bytes` and `string`.\n * Bugfix: Value transfer used in clone contracts.\n * Bugfix: Problem with strings as mapping keys.\n * Bugfix: Prevent usage of some operators.\n\n### 0.1.1 (2015-08-04)\n\n * Strings can be used as mapping keys.\n * Clone contracts.\n * Mapping members are skipped for structs in memory.\n * Use only a single stack slot for storage references.\n * Improved error message for wrong argument count. (#2456)\n * Bugfix: Fix comparison between `bytesXX` types. (#2087)\n * Bugfix: Do not allow floats for integer literals. (#2078)\n * Bugfix: Some problem with many local variables. (#2478)\n * Bugfix: Correctly initialise `string` and `bytes` state variables.\n * Bugfix: Correctly compute gas requirements for callcode.\n\n### 0.1.0 (2015-07-10)\n" }, { "path": "LICENSE.txt", "content": " GNU GENERAL PUBLIC LICENSE\n Version 3, 29 June 2007\n\n Copyright (C) 2007 Free Software Foundation, Inc. \n Everyone is permitted to copy and distribute verbatim copies\n of this license document, but changing it is not allowed.\n\n Preamble\n\n The GNU General Public License is a free, copyleft license for\nsoftware and other kinds of works.\n\n The licenses for most software and other practical works are designed\nto take away your freedom to share and change the works. By contrast,\nthe GNU General Public License is intended to guarantee your freedom to\nshare and change all versions of a program--to make sure it remains free\nsoftware for all its users. We, the Free Software Foundation, use the\nGNU General Public License for most of our software; it applies also to\nany other work released this way by its authors. You can apply it to\nyour programs, too.\n\n When we speak of free software, we are referring to freedom, not\nprice. Our General Public Licenses are designed to make sure that you\nhave the freedom to distribute copies of free software (and charge for\nthem if you wish), that you receive source code or can get it if you\nwant it, that you can change the software or use pieces of it in new\nfree programs, and that you know you can do these things.\n\n To protect your rights, we need to prevent others from denying you\nthese rights or asking you to surrender the rights. Therefore, you have\ncertain responsibilities if you distribute copies of the software, or if\nyou modify it: responsibilities to respect the freedom of others.\n\n For example, if you distribute copies of such a program, whether\ngratis or for a fee, you must pass on to the recipients the same\nfreedoms that you received. You must make sure that they, too, receive\nor can get the source code. And you must show them these terms so they\nknow their rights.\n\n Developers that use the GNU GPL protect your rights with two steps:\n(1) assert copyright on the software, and (2) offer you this License\ngiving you legal permission to copy, distribute and/or modify it.\n\n For the developers' and authors' protection, the GPL clearly explains\nthat there is no warranty for this free software. For both users' and\nauthors' sake, the GPL requires that modified versions be marked as\nchanged, so that their problems will not be attributed erroneously to\nauthors of previous versions.\n\n Some devices are designed to deny users access to install or run\nmodified versions of the software inside them, although the manufacturer\ncan do so. This is fundamentally incompatible with the aim of\nprotecting users' freedom to change the software. The systematic\npattern of such abuse occurs in the area of products for individuals to\nuse, which is precisely where it is most unacceptable. Therefore, we\nhave designed this version of the GPL to prohibit the practice for those\nproducts. If such problems arise substantially in other domains, we\nstand ready to extend this provision to those domains in future versions\nof the GPL, as needed to protect the freedom of users.\n\n Finally, every program is threatened constantly by software patents.\nStates should not allow patents to restrict development and use of\nsoftware on general-purpose computers, but in those that do, we wish to\navoid the special danger that patents applied to a free program could\nmake it effectively proprietary. To prevent this, the GPL assures that\npatents cannot be used to render the program non-free.\n\n The precise terms and conditions for copying, distribution and\nmodification follow.\n\n TERMS AND CONDITIONS\n\n 0. Definitions.\n\n \"This License\" refers to version 3 of the GNU General Public License.\n\n \"Copyright\" also means copyright-like laws that apply to other kinds of\nworks, such as semiconductor masks.\n\n \"The Program\" refers to any copyrightable work licensed under this\nLicense. Each licensee is addressed as \"you\". \"Licensees\" and\n\"recipients\" may be individuals or organizations.\n\n To \"modify\" a work means to copy from or adapt all or part of the work\nin a fashion requiring copyright permission, other than the making of an\nexact copy. The resulting work is called a \"modified version\" of the\nearlier work or a work \"based on\" the earlier work.\n\n A \"covered work\" means either the unmodified Program or a work based\non the Program.\n\n To \"propagate\" a work means to do anything with it that, without\npermission, would make you directly or secondarily liable for\ninfringement under applicable copyright law, except executing it on a\ncomputer or modifying a private copy. Propagation includes copying,\ndistribution (with or without modification), making available to the\npublic, and in some countries other activities as well.\n\n To \"convey\" a work means any kind of propagation that enables other\nparties to make or receive copies. Mere interaction with a user through\na computer network, with no transfer of a copy, is not conveying.\n\n An interactive user interface displays \"Appropriate Legal Notices\"\nto the extent that it includes a convenient and prominently visible\nfeature that (1) displays an appropriate copyright notice, and (2)\ntells the user that there is no warranty for the work (except to the\nextent that warranties are provided), that licensees may convey the\nwork under this License, and how to view a copy of this License. If\nthe interface presents a list of user commands or options, such as a\nmenu, a prominent item in the list meets this criterion.\n\n 1. Source Code.\n\n The \"source code\" for a work means the preferred form of the work\nfor making modifications to it. \"Object code\" means any non-source\nform of a work.\n\n A \"Standard Interface\" means an interface that either is an official\nstandard defined by a recognized standards body, or, in the case of\ninterfaces specified for a particular programming language, one that\nis widely used among developers working in that language.\n\n The \"System Libraries\" of an executable work include anything, other\nthan the work as a whole, that (a) is included in the normal form of\npackaging a Major Component, but which is not part of that Major\nComponent, and (b) serves only to enable use of the work with that\nMajor Component, or to implement a Standard Interface for which an\nimplementation is available to the public in source code form. A\n\"Major Component\", in this context, means a major essential component\n(kernel, window system, and so on) of the specific operating system\n(if any) on which the executable work runs, or a compiler used to\nproduce the work, or an object code interpreter used to run it.\n\n The \"Corresponding Source\" for a work in object code form means all\nthe source code needed to generate, install, and (for an executable\nwork) run the object code and to modify the work, including scripts to\ncontrol those activities. However, it does not include the work's\nSystem Libraries, or general-purpose tools or generally available free\nprograms which are used unmodified in performing those activities but\nwhich are not part of the work. For example, Corresponding Source\nincludes interface definition files associated with source files for\nthe work, and the source code for shared libraries and dynamically\nlinked subprograms that the work is specifically designed to require,\nsuch as by intimate data communication or control flow between those\nsubprograms and other parts of the work.\n\n The Corresponding Source need not include anything that users\ncan regenerate automatically from other parts of the Corresponding\nSource.\n\n The Corresponding Source for a work in source code form is that\nsame work.\n\n 2. Basic Permissions.\n\n All rights granted under this License are granted for the term of\ncopyright on the Program, and are irrevocable provided the stated\nconditions are met. This License explicitly affirms your unlimited\npermission to run the unmodified Program. The output from running a\ncovered work is covered by this License only if the output, given its\ncontent, constitutes a covered work. This License acknowledges your\nrights of fair use or other equivalent, as provided by copyright law.\n\n You may make, run and propagate covered works that you do not\nconvey, without conditions so long as your license otherwise remains\nin force. You may convey covered works to others for the sole purpose\nof having them make modifications exclusively for you, or provide you\nwith facilities for running those works, provided that you comply with\nthe terms of this License in conveying all material for which you do\nnot control copyright. Those thus making or running the covered works\nfor you must do so exclusively on your behalf, under your direction\nand control, on terms that prohibit them from making any copies of\nyour copyrighted material outside their relationship with you.\n\n Conveying under any other circumstances is permitted solely under\nthe conditions stated below. Sublicensing is not allowed; section 10\nmakes it unnecessary.\n\n 3. Protecting Users' Legal Rights From Anti-Circumvention Law.\n\n No covered work shall be deemed part of an effective technological\nmeasure under any applicable law fulfilling obligations under article\n11 of the WIPO copyright treaty adopted on 20 December 1996, or\nsimilar laws prohibiting or restricting circumvention of such\nmeasures.\n\n When you convey a covered work, you waive any legal power to forbid\ncircumvention of technological measures to the extent such circumvention\nis effected by exercising rights under this License with respect to\nthe covered work, and you disclaim any intention to limit operation or\nmodification of the work as a means of enforcing, against the work's\nusers, your or third parties' legal rights to forbid circumvention of\ntechnological measures.\n\n 4. Conveying Verbatim Copies.\n\n You may convey verbatim copies of the Program's source code as you\nreceive it, in any medium, provided that you conspicuously and\nappropriately publish on each copy an appropriate copyright notice;\nkeep intact all notices stating that this License and any\nnon-permissive terms added in accord with section 7 apply to the code;\nkeep intact all notices of the absence of any warranty; and give all\nrecipients a copy of this License along with the Program.\n\n You may charge any price or no price for each copy that you convey,\nand you may offer support or warranty protection for a fee.\n\n 5. Conveying Modified Source Versions.\n\n You may convey a work based on the Program, or the modifications to\nproduce it from the Program, in the form of source code under the\nterms of section 4, provided that you also meet all of these conditions:\n\n a) The work must carry prominent notices stating that you modified\n it, and giving a relevant date.\n\n b) The work must carry prominent notices stating that it is\n released under this License and any conditions added under section\n 7. This requirement modifies the requirement in section 4 to\n \"keep intact all notices\".\n\n c) You must license the entire work, as a whole, under this\n License to anyone who comes into possession of a copy. This\n License will therefore apply, along with any applicable section 7\n additional terms, to the whole of the work, and all its parts,\n regardless of how they are packaged. This License gives no\n permission to license the work in any other way, but it does not\n invalidate such permission if you have separately received it.\n\n d) If the work has interactive user interfaces, each must display\n Appropriate Legal Notices; however, if the Program has interactive\n interfaces that do not display Appropriate Legal Notices, your\n work need not make them do so.\n\n A compilation of a covered work with other separate and independent\nworks, which are not by their nature extensions of the covered work,\nand which are not combined with it such as to form a larger program,\nin or on a volume of a storage or distribution medium, is called an\n\"aggregate\" if the compilation and its resulting copyright are not\nused to limit the access or legal rights of the compilation's users\nbeyond what the individual works permit. Inclusion of a covered work\nin an aggregate does not cause this License to apply to the other\nparts of the aggregate.\n\n 6. Conveying Non-Source Forms.\n\n You may convey a covered work in object code form under the terms\nof sections 4 and 5, provided that you also convey the\nmachine-readable Corresponding Source under the terms of this License,\nin one of these ways:\n\n a) Convey the object code in, or embodied in, a physical product\n (including a physical distribution medium), accompanied by the\n Corresponding Source fixed on a durable physical medium\n customarily used for software interchange.\n\n b) Convey the object code in, or embodied in, a physical product\n (including a physical distribution medium), accompanied by a\n written offer, valid for at least three years and valid for as\n long as you offer spare parts or customer support for that product\n model, to give anyone who possesses the object code either (1) a\n copy of the Corresponding Source for all the software in the\n product that is covered by this License, on a durable physical\n medium customarily used for software interchange, for a price no\n more than your reasonable cost of physically performing this\n conveying of source, or (2) access to copy the\n Corresponding Source from a network server at no charge.\n\n c) Convey individual copies of the object code with a copy of the\n written offer to provide the Corresponding Source. This\n alternative is allowed only occasionally and noncommercially, and\n only if you received the object code with such an offer, in accord\n with subsection 6b.\n\n d) Convey the object code by offering access from a designated\n place (gratis or for a charge), and offer equivalent access to the\n Corresponding Source in the same way through the same place at no\n further charge. You need not require recipients to copy the\n Corresponding Source along with the object code. If the place to\n copy the object code is a network server, the Corresponding Source\n may be on a different server (operated by you or a third party)\n that supports equivalent copying facilities, provided you maintain\n clear directions next to the object code saying where to find the\n Corresponding Source. Regardless of what server hosts the\n Corresponding Source, you remain obligated to ensure that it is\n available for as long as needed to satisfy these requirements.\n\n e) Convey the object code using peer-to-peer transmission, provided\n you inform other peers where the object code and Corresponding\n Source of the work are being offered to the general public at no\n charge under subsection 6d.\n\n A separable portion of the object code, whose source code is excluded\nfrom the Corresponding Source as a System Library, need not be\nincluded in conveying the object code work.\n\n A \"User Product\" is either (1) a \"consumer product\", which means any\ntangible personal property which is normally used for personal, family,\nor household purposes, or (2) anything designed or sold for incorporation\ninto a dwelling. In determining whether a product is a consumer product,\ndoubtful cases shall be resolved in favor of coverage. For a particular\nproduct received by a particular user, \"normally used\" refers to a\ntypical or common use of that class of product, regardless of the status\nof the particular user or of the way in which the particular user\nactually uses, or expects or is expected to use, the product. A product\nis a consumer product regardless of whether the product has substantial\ncommercial, industrial or non-consumer uses, unless such uses represent\nthe only significant mode of use of the product.\n\n \"Installation Information\" for a User Product means any methods,\nprocedures, authorization keys, or other information required to install\nand execute modified versions of a covered work in that User Product from\na modified version of its Corresponding Source. The information must\nsuffice to ensure that the continued functioning of the modified object\ncode is in no case prevented or interfered with solely because\nmodification has been made.\n\n If you convey an object code work under this section in, or with, or\nspecifically for use in, a User Product, and the conveying occurs as\npart of a transaction in which the right of possession and use of the\nUser Product is transferred to the recipient in perpetuity or for a\nfixed term (regardless of how the transaction is characterized), the\nCorresponding Source conveyed under this section must be accompanied\nby the Installation Information. But this requirement does not apply\nif neither you nor any third party retains the ability to install\nmodified object code on the User Product (for example, the work has\nbeen installed in ROM).\n\n The requirement to provide Installation Information does not include a\nrequirement to continue to provide support service, warranty, or updates\nfor a work that has been modified or installed by the recipient, or for\nthe User Product in which it has been modified or installed. Access to a\nnetwork may be denied when the modification itself materially and\nadversely affects the operation of the network or violates the rules and\nprotocols for communication across the network.\n\n Corresponding Source conveyed, and Installation Information provided,\nin accord with this section must be in a format that is publicly\ndocumented (and with an implementation available to the public in\nsource code form), and must require no special password or key for\nunpacking, reading or copying.\n\n 7. Additional Terms.\n\n \"Additional permissions\" are terms that supplement the terms of this\nLicense by making exceptions from one or more of its conditions.\nAdditional permissions that are applicable to the entire Program shall\nbe treated as though they were included in this License, to the extent\nthat they are valid under applicable law. If additional permissions\napply only to part of the Program, that part may be used separately\nunder those permissions, but the entire Program remains governed by\nthis License without regard to the additional permissions.\n\n When you convey a copy of a covered work, you may at your option\nremove any additional permissions from that copy, or from any part of\nit. (Additional permissions may be written to require their own\nremoval in certain cases when you modify the work.) You may place\nadditional permissions on material, added by you to a covered work,\nfor which you have or can give appropriate copyright permission.\n\n Notwithstanding any other provision of this License, for material you\nadd to a covered work, you may (if authorized by the copyright holders of\nthat material) supplement the terms of this License with terms:\n\n a) Disclaiming warranty or limiting liability differently from the\n terms of sections 15 and 16 of this License; or\n\n b) Requiring preservation of specified reasonable legal notices or\n author attributions in that material or in the Appropriate Legal\n Notices displayed by works containing it; or\n\n c) Prohibiting misrepresentation of the origin of that material, or\n requiring that modified versions of such material be marked in\n reasonable ways as different from the original version; or\n\n d) Limiting the use for publicity purposes of names of licensors or\n authors of the material; or\n\n e) Declining to grant rights under trademark law for use of some\n trade names, trademarks, or service marks; or\n\n f) Requiring indemnification of licensors and authors of that\n material by anyone who conveys the material (or modified versions of\n it) with contractual assumptions of liability to the recipient, for\n any liability that these contractual assumptions directly impose on\n those licensors and authors.\n\n All other non-permissive additional terms are considered \"further\nrestrictions\" within the meaning of section 10. If the Program as you\nreceived it, or any part of it, contains a notice stating that it is\ngoverned by this License along with a term that is a further\nrestriction, you may remove that term. If a license document contains\na further restriction but permits relicensing or conveying under this\nLicense, you may add to a covered work material governed by the terms\nof that license document, provided that the further restriction does\nnot survive such relicensing or conveying.\n\n If you add terms to a covered work in accord with this section, you\nmust place, in the relevant source files, a statement of the\nadditional terms that apply to those files, or a notice indicating\nwhere to find the applicable terms.\n\n Additional terms, permissive or non-permissive, may be stated in the\nform of a separately written license, or stated as exceptions;\nthe above requirements apply either way.\n\n 8. Termination.\n\n You may not propagate or modify a covered work except as expressly\nprovided under this License. Any attempt otherwise to propagate or\nmodify it is void, and will automatically terminate your rights under\nthis License (including any patent licenses granted under the third\nparagraph of section 11).\n\n However, if you cease all violation of this License, then your\nlicense from a particular copyright holder is reinstated (a)\nprovisionally, unless and until the copyright holder explicitly and\nfinally terminates your license, and (b) permanently, if the copyright\nholder fails to notify you of the violation by some reasonable means\nprior to 60 days after the cessation.\n\n Moreover, your license from a particular copyright holder is\nreinstated permanently if the copyright holder notifies you of the\nviolation by some reasonable means, this is the first time you have\nreceived notice of violation of this License (for any work) from that\ncopyright holder, and you cure the violation prior to 30 days after\nyour receipt of the notice.\n\n Termination of your rights under this section does not terminate the\nlicenses of parties who have received copies or rights from you under\nthis License. If your rights have been terminated and not permanently\nreinstated, you do not qualify to receive new licenses for the same\nmaterial under section 10.\n\n 9. Acceptance Not Required for Having Copies.\n\n You are not required to accept this License in order to receive or\nrun a copy of the Program. Ancillary propagation of a covered work\noccurring solely as a consequence of using peer-to-peer transmission\nto receive a copy likewise does not require acceptance. However,\nnothing other than this License grants you permission to propagate or\nmodify any covered work. These actions infringe copyright if you do\nnot accept this License. Therefore, by modifying or propagating a\ncovered work, you indicate your acceptance of this License to do so.\n\n 10. Automatic Licensing of Downstream Recipients.\n\n Each time you convey a covered work, the recipient automatically\nreceives a license from the original licensors, to run, modify and\npropagate that work, subject to this License. You are not responsible\nfor enforcing compliance by third parties with this License.\n\n An \"entity transaction\" is a transaction transferring control of an\norganization, or substantially all assets of one, or subdividing an\norganization, or merging organizations. If propagation of a covered\nwork results from an entity transaction, each party to that\ntransaction who receives a copy of the work also receives whatever\nlicenses to the work the party's predecessor in interest had or could\ngive under the previous paragraph, plus a right to possession of the\nCorresponding Source of the work from the predecessor in interest, if\nthe predecessor has it or can get it with reasonable efforts.\n\n You may not impose any further restrictions on the exercise of the\nrights granted or affirmed under this License. For example, you may\nnot impose a license fee, royalty, or other charge for exercise of\nrights granted under this License, and you may not initiate litigation\n(including a cross-claim or counterclaim in a lawsuit) alleging that\nany patent claim is infringed by making, using, selling, offering for\nsale, or importing the Program or any portion of it.\n\n 11. Patents.\n\n A \"contributor\" is a copyright holder who authorizes use under this\nLicense of the Program or a work on which the Program is based. The\nwork thus licensed is called the contributor's \"contributor version\".\n\n A contributor's \"essential patent claims\" are all patent claims\nowned or controlled by the contributor, whether already acquired or\nhereafter acquired, that would be infringed by some manner, permitted\nby this License, of making, using, or selling its contributor version,\nbut do not include claims that would be infringed only as a\nconsequence of further modification of the contributor version. For\npurposes of this definition, \"control\" includes the right to grant\npatent sublicenses in a manner consistent with the requirements of\nthis License.\n\n Each contributor grants you a non-exclusive, worldwide, royalty-free\npatent license under the contributor's essential patent claims, to\nmake, use, sell, offer for sale, import and otherwise run, modify and\npropagate the contents of its contributor version.\n\n In the following three paragraphs, a \"patent license\" is any express\nagreement or commitment, however denominated, not to enforce a patent\n(such as an express permission to practice a patent or covenant not to\nsue for patent infringement). To \"grant\" such a patent license to a\nparty means to make such an agreement or commitment not to enforce a\npatent against the party.\n\n If you convey a covered work, knowingly relying on a patent license,\nand the Corresponding Source of the work is not available for anyone\nto copy, free of charge and under the terms of this License, through a\npublicly available network server or other readily accessible means,\nthen you must either (1) cause the Corresponding Source to be so\navailable, or (2) arrange to deprive yourself of the benefit of the\npatent license for this particular work, or (3) arrange, in a manner\nconsistent with the requirements of this License, to extend the patent\nlicense to downstream recipients. \"Knowingly relying\" means you have\nactual knowledge that, but for the patent license, your conveying the\ncovered work in a country, or your recipient's use of the covered work\nin a country, would infringe one or more identifiable patents in that\ncountry that you have reason to believe are valid.\n\n If, pursuant to or in connection with a single transaction or\narrangement, you convey, or propagate by procuring conveyance of, a\ncovered work, and grant a patent license to some of the parties\nreceiving the covered work authorizing them to use, propagate, modify\nor convey a specific copy of the covered work, then the patent license\nyou grant is automatically extended to all recipients of the covered\nwork and works based on it.\n\n A patent license is \"discriminatory\" if it does not include within\nthe scope of its coverage, prohibits the exercise of, or is\nconditioned on the non-exercise of one or more of the rights that are\nspecifically granted under this License. You may not convey a covered\nwork if you are a party to an arrangement with a third party that is\nin the business of distributing software, under which you make payment\nto the third party based on the extent of your activity of conveying\nthe work, and under which the third party grants, to any of the\nparties who would receive the covered work from you, a discriminatory\npatent license (a) in connection with copies of the covered work\nconveyed by you (or copies made from those copies), or (b) primarily\nfor and in connection with specific products or compilations that\ncontain the covered work, unless you entered into that arrangement,\nor that patent license was granted, prior to 28 March 2007.\n\n Nothing in this License shall be construed as excluding or limiting\nany implied license or other defenses to infringement that may\notherwise be available to you under applicable patent law.\n\n 12. No Surrender of Others' Freedom.\n\n If conditions are imposed on you (whether by court order, agreement or\notherwise) that contradict the conditions of this License, they do not\nexcuse you from the conditions of this License. If you cannot convey a\ncovered work so as to satisfy simultaneously your obligations under this\nLicense and any other pertinent obligations, then as a consequence you may\nnot convey it at all. For example, if you agree to terms that obligate you\nto collect a royalty for further conveying from those to whom you convey\nthe Program, the only way you could satisfy both those terms and this\nLicense would be to refrain entirely from conveying the Program.\n\n 13. Use with the GNU Affero General Public License.\n\n Notwithstanding any other provision of this License, you have\npermission to link or combine any covered work with a work licensed\nunder version 3 of the GNU Affero General Public License into a single\ncombined work, and to convey the resulting work. The terms of this\nLicense will continue to apply to the part which is the covered work,\nbut the special requirements of the GNU Affero General Public License,\nsection 13, concerning interaction through a network will apply to the\ncombination as such.\n\n 14. Revised Versions of this License.\n\n The Free Software Foundation may publish revised and/or new versions of\nthe GNU General Public License from time to time. Such new versions will\nbe similar in spirit to the present version, but may differ in detail to\naddress new problems or concerns.\n\n Each version is given a distinguishing version number. If the\nProgram specifies that a certain numbered version of the GNU General\nPublic License \"or any later version\" applies to it, you have the\noption of following the terms and conditions either of that numbered\nversion or of any later version published by the Free Software\nFoundation. If the Program does not specify a version number of the\nGNU General Public License, you may choose any version ever published\nby the Free Software Foundation.\n\n If the Program specifies that a proxy can decide which future\nversions of the GNU General Public License can be used, that proxy's\npublic statement of acceptance of a version permanently authorizes you\nto choose that version for the Program.\n\n Later license versions may give you additional or different\npermissions. However, no additional obligations are imposed on any\nauthor or copyright holder as a result of your choosing to follow a\nlater version.\n\n 15. Disclaimer of Warranty.\n\n THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY\nAPPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT\nHOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM \"AS IS\" WITHOUT WARRANTY\nOF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,\nTHE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR\nPURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM\nIS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF\nALL NECESSARY SERVICING, REPAIR OR CORRECTION.\n\n 16. Limitation of Liability.\n\n IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING\nWILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS\nTHE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY\nGENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE\nUSE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF\nDATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD\nPARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),\nEVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF\nSUCH DAMAGES.\n\n 17. Interpretation of Sections 15 and 16.\n\n If the disclaimer of warranty and limitation of liability provided\nabove cannot be given local legal effect according to their terms,\nreviewing courts shall apply local law that most closely approximates\nan absolute waiver of all civil liability in connection with the\nProgram, unless a warranty or assumption of liability accompanies a\ncopy of the Program in return for a fee.\n\n END OF TERMS AND CONDITIONS\n\n How to Apply These Terms to Your New Programs\n\n If you develop a new program, and you want it to be of the greatest\npossible use to the public, the best way to achieve this is to make it\nfree software which everyone can redistribute and change under these terms.\n\n To do so, attach the following notices to the program. It is safest\nto attach them to the start of each source file to most effectively\nstate the exclusion of warranty; and each file should have at least\nthe \"copyright\" line and a pointer to where the full notice is found.\n\n \n Copyright (C) \n\n This program is free software: you can redistribute it and/or modify\n it under the terms of the GNU General Public License as published by\n the Free Software Foundation, either version 3 of the License, or\n (at your option) any later version.\n\n This program is distributed in the hope that it will be useful,\n but WITHOUT ANY WARRANTY; without even the implied warranty of\n MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n GNU General Public License for more details.\n\n You should have received a copy of the GNU General Public License\n along with this program. If not, see .\n\nAlso add information on how to contact you by electronic and paper mail.\n\n If the program does terminal interaction, make it output a short\nnotice like this when it starts in an interactive mode:\n\n Copyright (C) \n This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.\n This is free software, and you are welcome to redistribute it\n under certain conditions; type `show c' for details.\n\nThe hypothetical commands `show w' and `show c' should show the appropriate\nparts of the General Public License. Of course, your program's commands\nmight be different; for a GUI interface, you would use an \"about box\".\n\n You should also get your employer (if you work as a programmer) or school,\nif any, to sign a \"copyright disclaimer\" for the program, if necessary.\nFor more information on this, and how to apply and follow the GNU GPL, see\n.\n\n The GNU General Public License does not permit incorporating your program\ninto proprietary programs. If your program is a subroutine library, you\nmay consider it more useful to permit linking proprietary applications with\nthe library. If this is what you want to do, use the GNU Lesser General\nPublic License instead of this License. But first, please read\n.\n\n" }, { "path": "README.md", "content": "# The Solidity Contract-Oriented Programming Language\n\n[![Matrix Chat](https://img.shields.io/badge/Matrix%20-chat-brightgreen?style=plastic&logo=matrix)](https://matrix.to/#/#ethereum_solidity:gitter.im)\n[![Gitter Chat](https://img.shields.io/badge/Gitter%20-chat-brightgreen?style=plastic&logo=gitter)](https://gitter.im/ethereum/solidity)\n[![Solidity Forum](https://img.shields.io/badge/Solidity_Forum%20-discuss-brightgreen?style=plastic&logo=discourse)](https://forum.soliditylang.org/)\n[![X Follow](https://img.shields.io/twitter/follow/solidity_lang?style=plastic&logo=x)](https://X.com/solidity_lang)\n[![Mastodon Follow](https://img.shields.io/mastodon/follow/000335908?domain=https%3A%2F%2Ffosstodon.org%2F&logo=mastodon&style=plastic)](https://fosstodon.org/@solidity)\n\nYou can talk to us on Gitter and Matrix, tweet at us on X (previously Twitter) or create a new topic in the Solidity forum. Questions, feedback, and suggestions are welcome!\n\nSolidity is a statically-typed, contract-oriented, high-level language for implementing smart contracts on the Ethereum platform.\n\nFor a good overview and starting point, please check out the official [Solidity Language Portal](https://soliditylang.org).\n\n## Table of Contents\n\n- [Background](#background)\n- [Build and Install](#build-and-install)\n- [Example](#example)\n- [Documentation](#documentation)\n- [Development](#development)\n- [Maintainers](#maintainers)\n- [License](#license)\n- [Security](#security)\n\n## Background\n\nSolidity is a statically-typed curly-braces programming language designed for developing smart contracts\nthat run on the Ethereum Virtual Machine. Smart contracts are programs that are executed inside a peer-to-peer\nnetwork where nobody has special authority over the execution, and thus they allow anyone to implement tokens of value,\nownership, voting, and other kinds of logic.\n\nWhen deploying contracts, you should use the latest released version of\nSolidity. This is because breaking changes, as well as new features and bug fixes, are\nintroduced regularly. We currently use a 0.x version\nnumber [to indicate this fast pace of change](https://semver.org/#spec-item-4).\n\n## Build and Install\n\nInstructions about how to build and install the Solidity compiler can be\nfound in the [Solidity documentation](https://docs.soliditylang.org/en/latest/installing-solidity.html#building-from-source).\n\n\n## Example\n\nA \"Hello World\" program in Solidity is of even less use than in other languages, but still:\n\n```solidity\n// SPDX-License-Identifier: MIT\npragma solidity >=0.6.0 <0.9.0;\n\ncontract HelloWorld {\n function helloWorld() external pure returns (string memory) {\n return \"Hello, World!\";\n }\n}\n```\n\nTo get started with Solidity, you can use [Remix](https://remix.ethereum.org/), which is a\nbrowser-based IDE. Here are some example contracts:\n\n1. [Voting](https://docs.soliditylang.org/en/latest/solidity-by-example.html#voting)\n2. [Blind Auction](https://docs.soliditylang.org/en/latest/solidity-by-example.html#blind-auction)\n3. [Safe remote purchase](https://docs.soliditylang.org/en/latest/solidity-by-example.html#safe-remote-purchase)\n4. [Micropayment Channel](https://docs.soliditylang.org/en/latest/solidity-by-example.html#micropayment-channel)\n\n## Documentation\n\nThe Solidity documentation is hosted using [Read the Docs](https://docs.soliditylang.org).\n\n## Development\n\nSolidity is still under development. Contributions are always welcome!\nPlease follow the\n[Developer's Guide](https://docs.soliditylang.org/en/latest/contributing.html)\nif you want to help.\n\nYou can find our current feature and bug priorities for forthcoming\nreleases in the [projects section](https://github.com/argotorg/solidity/projects).\n\n## Maintainers\nThe Solidity programming language and compiler are open-source community projects governed by a core team.\nThe core team is sponsored by the [Ethereum Foundation](https://ethereum.foundation/).\n\n## License\nSolidity is licensed under [GNU General Public License v3.0](LICENSE.txt).\n\nSome third-party code has its [own licensing terms](cmake/templates/license.h.in).\n\n## Security\n\nThe security policy may be [found here](SECURITY.md).\n" }, { "path": "ReleaseChecklist.md", "content": "# Checklist for making a Solidity release\n\n## Requirements\n- GitHub account with access to [solidity](https://github.com/argotorg/solidity), [solc-js](https://github.com/argotorg/solc-js),\n [solc-bin](https://github.com/argotorg/solc-bin), [solidity-website](https://github.com/argotorg/solidity-website).\n- Personal Access Token (PAT) with `write:packages` scope to access Github's container registry.\n You can generate one by visiting https://github.com/settings/tokens/new?scopes=write:packages.\n- Ubuntu/Debian dependencies of the Docker script: `docker-buildx`.\n- [npm Registry](https://www.npmjs.com) account added as a collaborator for the [`solc` package](https://www.npmjs.com/package/solc).\n- Access to the [solidity_lang Twitter account](https://twitter.com/solidity_lang).\n- [Reddit](https://www.reddit.com) account that is at least 10 days old with a minimum of 20 comment karma (`/r/ethereum` requirements).\n\n## Full release\n\n### Pre-flight checks\nAt least a day before the release:\n- [ ] Run `make linkcheck` from within `docs/` and fix any broken links it finds.\n Ignore false positives caused by `href` anchors and dummy links not meant to work.\n **Note**: In order to run the link check, make sure you've built the docs first via `docs.sh`.\n- [ ] Double-check that [the most recent docs builds at readthedocs](https://readthedocs.org/projects/solidity/builds/) succeeded.\n- [ ] Make sure that all merged PRs that should have changelog entries do have them.\n- [ ] 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:\n - [ ] `solc-js`\n - [ ] `solc-bin` (make sure the bytecode comparison check did run)\n- [ ] Verify that the release tarball of `solc-js` works.\n 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.\n- [ ] Review [Learning from Past Releases](https://notes.argot.org/@solidity-release-mistakes) to make sure you don't repeat the same mistakes.\n\n### Drafts\nAt least a day before the release:\n- [ ] Create a draft PR to sort the changelog.\n- [ ] Create draft PRs to bump version in `solidity` and `solc-js`.\n **Note**: The `solc-js` PR won't pass CI checks yet because it depends on the soljson binary from `solc-bin`.\n- [ ] Create a draft of the release on github.\n- [ ] Create a draft PR to update soliditylang.org.\n- [ ] Create drafts of blog posts.\n- [ ] Prepare drafts of Twitter, Reddit and Solidity Forum announcements.\n\n### Website/Blog Updates\n- [ ] Create a post on [solidity-website](https://github.com/argotorg/solidity-website/tree/main/src/posts) in the `Releases` category and explain some of the new features or concepts.\n- [ ] Create a post on [solidity-website](https://github.com/argotorg/solidity-website/tree/main/src/posts) in the `Security Alerts` category in case of important bug(s).\n- [ ] Update the release information section [in the source of soliditylang.org](https://github.com/argotorg/solidity-website/blob/main/src/pages/index.tsx).\n- [ ] Get the PR(s) for the above reviewed and approved **before the release starts**, but don't merge them yet.\n\n### Changelog\n- [ ] Ensure that all changelog entries are correctly classified as language or compiler features.\n- [ ] Sort the changelog entries alphabetically and correct any errors you notice. Commit it.\n- [ ] Update the changelog to include a release date.\n- [ ] Run `scripts/update_bugs_by_version.py` to regenerate `bugs_by_version.json` from the changelog and `bugs.json`.\n Make sure that the resulting `bugs_by_version.json` has a new, empty entry for the new version.\n- [ ] Commit changes, create a pull request and wait for the tests. Then merge it.\n- [ ] Copy the changelog into the release blog post.\n\n### Create the Release\n- [ ] Create a [release on GitHub](https://github.com/argotorg/solidity/releases/new).\n Set the target to the `develop` branch and the tag to the new version, e.g. `v0.8.5`.\n Include the following warning: `**The release is still in progress. You may see broken links and binaries may not yet be available from all sources.**`.\n Do not publish it yet - click the `Save draft` button instead.\n- [ ] Thank voluntary contributors in the GitHub release notes.\n Use `scripts/list_contributors.sh v` to get initial list of names.\n Remove different variants of the same name manually before using the output.\n- [ ] Check that all tests on the latest commit on `develop` are green.\n- [ ] Click the `Publish release` button on the release page, creating the tag.\n **Important: Must not be done before all the PRs, including changelog cleanup and date, are merged.**\n- [ ] Wait for the CI runs on the tag itself.\n\n### Upload Release Artifacts and Publish Binaries\n- [ ] Take the source tarball (`solidity_x.x.x.tar.gz`) from `c_source_tarball` run of the tagged commit on Circle CI and upload it to the release page.\n- [ ] Take the `github-binaries.tar` tarball from `c_release_binaries` run of the tagged commit on Circle CI and add all binaries from it to the release page.\n Make sure it contains five binaries: `solc-windows.exe`, `solc-macos`, `solc-static-linux`, `solc-static-linux-arm`, and `soljson.js`.\n- [ ] Take the `solc-bin-binaries.tar` tarball from `c_release_binaries` run of the tagged commit on Circle CI and add all binaries from it to solc-bin.\n- [ ] Run `npm install` if you've got a clean checkout of the solc-bin repo.\n- [ ] 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/`.\n- [ ] Create a pull request in solc-bin and merge.\n\n### Homebrew and MacOS\n- [ ] 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/s/solidity.rb).\n\n### Docker\n- [ ] Make sure `docker-buildx` is installed.\n- [ ] Run `echo $GHCR_TOKEN | docker login ghcr.io --username $GH_USERNAME --password-stdin` where `$GH_USERNAME` is your GitHub username and `$GHCR_TOKEN` is a PAT with `write:packages` scope.\n- [ ] Run `./scripts/docker_deploy_manual.sh v$VERSION`.\n\n### Release solc-js\n- [ ] Wait until solc-bin was properly deployed. You can test this via remix - a test run through remix is advisable anyway.\n- [ ] Increment the version number, create a pull request for that, merge it after tests succeeded.\n- [ ] Create a tag using `git tag --annotate v$VERSION` and push it with `git push --tags`.\n- [ ] Wait for the CI runs on the tag itself.\n- [ ] Take the `solc-x.y.z.tgz` artifact from `build-package` run on the tagged commit on Circle CI.\n Inspect the tarball to ensure that it contains an up-to-date compiler binary (`soljson.js`).\n- [ ] Run `npm publish solc-x.y.z.tgz` to publish the newly created tarball.\n\n### Documentation\n- [ ] Make sure the documentation for the new release has been published successfully.\n 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.\n- [ ] Remove \"still in progress\" warning from the [release notes](https://github.com/argotorg/solidity/releases).\n\n### Comms\n- [ ] Merge the blog posts and website updates prepared for the release.\n- [ ] Verify that the link to the blog post in [release notes](https://github.com/argotorg/solidity/releases) is not broken.\n- [ ] Announce on [Twitter](https://twitter.com/solidity_lang), including links to the release and the blog post.\n- [ ] Announce on [Fosstodon](https://fosstodon.org/@solidity/), including links to the release and the blog post.\n- [ ] Share the announcement on Reddit in [`/r/ethdev`](https://reddit.com/r/ethdev/), cross-posted to [`/r/ethereum`](https://reddit.com/r/ethereum/).\n- [ ] Share the announcement on the [Solidity forum](https://forum.soliditylang.org) in the `Announcements` category.\n- [ ] Share the announcement on [`#solidity` channel on Matrix](https://matrix.to/#/#ethereum_solidity:gitter.im).\n- [ ] Share the announcement on [`#solc-tooling`](https://matrix.to/#/#solc-tooling:matrix.org).\n\n### Post-release\n- [ ] Create a commit to increase the version number on `develop` in `CMakeLists.txt` and add a new skeleton changelog entry.\n- [ ] If anything went wrong this time, mention it in [Learning from Past Releases](https://notes.argot.org/@solidity-release-mistakes).\n- [ ] Bump vendored dependencies.\n- [ ] Lean back, wait for bug reports and repeat from step 1 :).\n\n## Prerelease\n- [ ] Check that all tests on the latest commit on `develop` or `breaking` branch (whichever was chosen for the prerelease) are green.\n- [ ] Create a [release on GitHub](https://github.com/argotorg/solidity/releases/new).\n - Set the target to the `develop` or `breaking` branch and the tag to the new version with a prerelease suffix, e.g. `v0.8.5-pre.6`.\n Version matches the next release (`develop`) or the next breaking release (`breaking`).\n The prerelease number in the suffix is 1-based, sequential, resets after a full release and is counted separately for `develop` and `breaking`.\n - Include the following warning: `**The release is still in progress. You may see broken links and binaries may not yet be available from all sources.**`.\n - Include the current, incomplete changelog.\n - Check the `Set as a pre-release` box.\n - Click the `Publish release` button on the release page, creating the tag.\n- [ ] Wait for the CI runs on the tag itself.\n- [ ] Take the source tarball (`solidity_x.x.x-pre.N.tar.gz`) from `c_source_tarball` run of the tagged commit on Circle CI and upload it to the release page.\n- [ ] Take the `github-binaries.tar` tarball from `c_release_binaries` run of the tagged commit on Circle CI and add all binaries from it to the release page.\n Make sure it contains five binaries: `solc-windows.exe`, `solc-macos`, `solc-static-linux`, `solc-static-linux-arm` and `soljson.js`.\n- [ ] Take the `solc-bin-binaries.tar` tarball from `c_release_binaries` run of the tagged commit on Circle CI and add all binaries from it to solc-bin.\n- [ ] Run `npm install` if you've got a clean checkout of the solc-bin repo.\n- [ ] 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/`.\n- [ ] Create a pull request in solc-bin and merge.\n- [ ] Remove \"still in progress\" warning from the [release notes](https://github.com/argotorg/solidity/releases).\n- [ ] Mention it on [Twitter](https://twitter.com/solidity_lang).\n- [ ] Mention it on [Fosstodon](https://fosstodon.org/@solidity/).\n- [ ] Mention it on [`#solidity` channel on Matrix](https://matrix.to/#/#ethereum_solidity:gitter.im).\n- [ ] Mention it on [`#solc-tooling`](https://matrix.to/#/#solc-tooling:matrix.org).\n- [ ] If anything went wrong this time, mention it in [Learning from Past Releases](https://notes.argot.org/@solidity-release-mistakes).\n- [ ] Lean back, wait for bug reports and repeat from step 1 :).\n" }, { "path": "ReviewChecklist.md", "content": "# PR Review Checklist\nThe Solidity compiler is a critical piece of infrastructure in the Ethereum ecosystem.\nFor this reason, our review process is quite strict and all PRs have to fulfill certain quality\nexpectations and guidelines.\nThe list below is meant to reduce the workload on the core team by helping contributors self-identify\nand solve common issues before they are pointed out in the review.\nIt is also meant to serve as a final checklist for reviewers to go through before approving a PR.\n\n## Before You Submit a PR\n- [ ] **Do you have any other open PRs?**\n Work on a PR is not done until it is merged or closed.\n Our reviewing capacity is limited, so we require that external contributors work on **no more than one PR at a time**.\n - 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.\n - Unless they were requested, we are going to close any excess PRs, leaving only the earliest one open.\n You may reopen them, one at a time, when your current PR is done.\n- [ ] **Is the issue ready to be worked on?**\n - If the issue does not have a desirability label (`nice to have`, `should have`,\n `must have eventually`, `must have`, `roadmap`) we have not yet decided whether to implement it.\n - If the issue has the `needs design` label, we have not yet decided how it should be implemented.\n - `good first issue candidate` means that the issue will potentially be a `good first issue`\n eventually but at the moment it is not yet ready to be worked on.\n- [ ] **Is this a breaking change?** Breaking changes should be based on the `breaking` branch rather than on the `develop` branch.\n- [ ] **Does the PR actually address the issue?**\n - [ ] Mention the issue number in the PR description.\n If the PR solves it completely, use the `Fixes #` form so that Github will close the issue automatically.\n - [ ] Do not include the issue number in the PR title, branch name or commit description.\n- [ ] When submitting a PR from a fork **create a branch and give it a descriptive name.**\n E.g. `fix-array-abi-encoding-bug`.\n Do not submit PRs directly from the `develop` branch of your fork since it makes rebasing and fetching new changes harder.\n- [ ] **Does the PR depend on other PRs?**\n - [ ] If the PR has dependencies, mention them in bold in the description.\n - [ ] Avoid basing PRs from forks on branches other than `develop` or `breaking` because\n GitHub closes them when the base branch gets merged.\n Do this only for PRs created directly in the main repo.\n- [ ] **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.\n In many cases the expectations can be updated automatically:\n - `cmdlineTests.sh --update` for command-line tests.\n - `isoltest --enforce-gas-cost --accept-updates` for soltest-based tests.\n - 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.\n - Review updated files before committing them.\n **Are expectations correct and do updated tests still serve their purpose?**\n\n## Abandoned PRs\n- [ ] **Is the submitter still responsive?**\n - If the PR had no activity from the submitter in the last 2 weeks (despite receiving reviews and our prompts) we consider it abandoned.\n- [ ] **Is the abandoned PR easy to finish or relevant?**\n - Apply the `takeover` label if the PR can be finished without significant effort or is something that actually needs to be done right now.\n Otherwise close it.\n It can still be taken over later or reopened by the submitter but until then we should not be getting sidetracked by it.\n\n## Light Review\nBefore an in-depth review, it is recommended to give new PRs a quick, superficial review, which\nis not meant to provide complete and detailed feedback, but instead give the submitter a rough idea\nif the PR is even on the right track and let them solve the obvious problems on their own.\n\nLight review should focus on the following three areas:\n- [ ] **Are there any obvious mistakes?** Style issues, bad practices, easy to identify bugs, etc.\n- [ ] **Is there anything missing?** Tests (of the right kind), documentation, etc. Does it address the whole issue?\n- [ ] **Is it the right solution?** Are there better ways to do this? Is the change even necessary?\n\nIf the answers above are \"Yes, Yes, No\", thank the contributor for their effort and **close the PR**.\n\n## Coding Style and Good Practices\n- [ ] Does the PR follow our [coding style](CODING_STYLE.md)?\n\n### Reliability\n- [ ] **Use assertions liberally.** If you are certain your assumption will not be broken, prove it with `solAssert()`.\n- [ ] **Validate inputs and handle errors**. Note that assertions are **not** validation.\n\n### Readability\n- [ ] **Choose good names.**\n - [ ] Is the name straightforward to understand?\n Do you feel the need to jump back to the definition and remind yourself what it was whenever you see it?\n - [ ] Is the name unambiguous in the context where it is used?\n - [ ] Avoid abbreviations.\n- [ ] **Source files, classes and public functions should have docstrings.**\n- [ ] **Avoid code duplication.** But not fanatically. Minimal amounts of duplication are acceptable if it aids readability.\n- [ ] **Do not leave dead or commented-out code behind.** You can still see old code in history.\n If you really have a good reason to do it, always leave a comment explaining what it is and why it is there.\n- [ ] **Mark hacks as such.** If you have to leave behind a temporary workaround, make\n sure to include a comment that explains why and in what circumstances it can be removed.\n Preferably link to an issue you reported upstream.\n- [ ] **Avoid obvious comments.**\n- [ ] **Do include comments when the reader may need extra context to understand the code.**\n\n### Commits and PRs\n- [ ] **Avoid hiding functional changes inside refactors.**\n E.g. when fixing a small bug, or changing user-visible behavior, put the change in a separate commit.\n Do not mix it with another change that renames things or reformats the code around, making the fix itself hard to identify.\n- [ ] **Whenever possible, split off refactors or unrelated changes into separate PRs.**\n Smaller PRs are easier and quicker to review.\n Splitting off refactors helps focus on the main point of the PR.\n\n### Common Pitfalls\nThe following points are all covered by the coding style but come up so often that it is worth singling them out here:\n- [ ] **Always initialize value types in the definition,** even if you are sure you will assign them later.\n- [ ] **Use \"east const\" style.** I.e. `T const*`, not `const T *`.\n- [ ] **Keep indentation consistent.** See our [`.editorconfig`](.editorconfig).\n - [ ] Tabs for C++. But use them for indentation only. Any whitespace later on the line must consist of spaces.\n - [ ] 4 spaces for most other file types.\n- [ ] **Use `auto` sparingly.** Only use it when the actual type is very long and complicated or when it is\n already used elsewhere in the same expression.\n- [ ] **Indent braces and parentheses in a way that makes nesting clear.**\n- [ ] **Use `using namespace` only in `.cpp` files.** Use it for `std` and our own modules.\n Avoid unnecessary `std::` prefix in `.cpp` files (except for `std::move` and `std::forward`).\n- [ ] **Use range-based loops and destructuring.**\n- [ ] **Include any headers you use directly,** even if they are implicitly included through other headers.\n\n## Documentation\n- [ ] **Does the PR update relevant documentation?**\n\n### Documentation Style and Good Practices\n- [ ] **Use double backticks in RST (``` ``x`` ```). Prefer single backticks in Markdown (`` `x` ``),**\n but note that double backticks are valid too and we use them in some cases for legacy reasons.\n- [ ] **Always start a new sentence on a new line.**\n This way you do not have to rewrap the surrounding text when you rewrite the sentence.\n This also makes changes actually easier to spot in the diff.\n\n## Testing\n\n### What to Test\n- [ ] **Is newly added code adequately covered by tests?** Have you considered all the important corner cases?\n- If it is a bugfix:\n - [ ] **The PR must include tests that reproduce the bug.**\n - [ ] **Are there gaps in test coverage of the buggy feature?** Fill them by adding more tests.\n - [ ] **Try to break it.** Can you think of any similar features that could also be buggy?\n Play with the repro and include prominent variants as separate test cases, even if they don't trigger a bug.\n- [ ] **Positive cases (code that compiles) should have a semantic test.**\n- [ ] **Negative cases (code with compilation errors) should have a syntax test.**\n- [ ] **Avoid mixing positive and negative cases in the same syntax test.**\n If the test produces an error, we stop at the analysis stage and we will not detect\n problems that only occur in code generation, optimizer or assembler.\n - [ ] If you have to do it, at least mark positive cases inside the file with a short comment.\n - This way, when the test is updated, it is easier to verify that these cases still do not trigger an error.\n- [ ] New syntax: **does it have an [`ASTJSON`](test/libsolidity/ASTJSON/) test?**\n- [ ] New CLI or StandardJSON option:\n - [ ] **Does it have a [command-line test](test/cmdlineTests/)?**\n - [ ] **Is the option listed for every input mode in [`CommandLineParser` tests](test/solc/CommandLineParser.cpp)?**\n- [ ] **Did you consider interactions with other language features?**\n - [ ] Are all types covered? Structs? Enums? Contracts/libraries/interfaces? User-defined value types?\n Value types: integers, fixed bytes, `address`, `address payable`, `bool`? Function pointers?\n Static and dynamic arrays? `string` and `bytes`? Mappings?\n Values of types that cannot be named: literals, tuples, array slices, storage references?\n - [ ] If it accepts a function, does it also accept an event or an error? These have function types but are not functions.\n - [ ] If it affects free functions, what about internal library functions?\n - [ ] Attached library functions? Functions attached with `using for`?\n - [ ] Possible combinations of `storage`, `memory`, `calldata`, `immutable`, `constant`?\n Remember that internal functions can take `storage` arguments.\n - [ ] Does it work at construction time as well? What if you store it at construction time and read after deployment?\n - [ ] What about importing it from a different module or inheriting it?\n - [ ] Have you tested it with the ternary operator?\n\n### Test Style and Good Practices\n- [ ] **Make test case file names long and specific enough** so that it is easy to guess what is inside.\n When checking if we have the case already covered the name is usually the only clue we see.\n - [ ] Place them in the right subdirectory.\n - [ ] **Avoid simply appending numbers to the name to distinguish similar cases.**\n Coming up with good names is hard but figuring out if any of hundreds of tests with names that\n match your search actually fits your case is even harder.\n- [ ] **Do not include version pragma and the SPDX comment in semantic and syntax test cases**.\n In other test types include them if necessary to suppress warnings.\n- [ ] **If you have to use a version pragma, avoid hard-coding version.** Use `pragma solidity *`.\n- [ ] **When writing StandardJSON command-line tests, use `urls` instead of `content`** and put\n the Solidity or Yul code in a separate file.\n\n## Compiler-specific\n- [ ] **Are error messages sensible and understandable to users?**\n- [ ] **Are error codes consistent?**\n - [ ] Avoid randomly changing or reassigning error codes.\n - [ ] Avoid defining separate codes for trivial variants of the same issue.\n Make it easy for tools to consistently refer to the same error with the same code.\n- [ ] **Error messages should end with a full stop.**\n- [ ] **Prefer Ranges v3 to Boost where possible.**\n\n## Take a Step Back\n- [ ] **Do you fully understand what the PR does and why?**\n- [ ] **Are you confident that the code works and does not break unrelated functionality?**\n- [ ] **Is this a reasonable way to achieve the goal stated in the issue?**\n- [ ] **Is the code simple?** Does the PR achieve its objective at the cost of significant\n complexity that may be a source of future bugs?\n- [ ] **Is the code efficient?** Does the PR introduce any major performance bottlenecks?\n- [ ] **Does the PR introduce any breaking changes beyond what was agreed in the issue?**\n\n## Final Checks Before Merging\n- [ ] **Is the PR rebased on top of the `develop` branch** (or `breaking` if it is a breaking change)?\n- [ ] **Did all CI checks pass?**\n - Note that we have a few jobs that tend to randomly fail due to outside factors, especially external tests (with `_ext_` in the name).\n If these fail, rebase on latest `develop` (or `breaking`) and try rerunning them.\n Note also that not all of these checks are required for the PR to be merged.\n- [ ] If the change is visible to users, **does the PR have a [changelog](Changelog.md) entry?**\n - [ ] Is the changelog entry in the right section?\n Make sure to move it up if there was a release recently.\n- [ ] **Is commit history simple and understandable?**\n - [ ] Each commit should be a self-contained, logical step leading the goal of the PR, without going back and forth.\n In particular, review fixups should be squashed into the commits they fix.\n - [ ] Do not include any merge commits in your branch. Please use rebase to keep up to date with the base branch.\n- [ ] **Is the PR properly labeled?**\n - Use `external contribution` label to mark PRs not coming from the core team.\n - If the PR depends on other PRs, use `has dependencies` and set the base branch accordingly.\n - Labels like `documentation` or `optimizer` are helpful for filtering PRs.\n" }, { "path": "SECURITY.md", "content": "# Security Policy\n\nThe Solidity team and community take all security bugs in Solidity seriously.\nWe appreciate your efforts and responsible disclosure and will make every effort to acknowledge your contributions.\n\n## Scope\n\nBugs in the Solidity repository are in scope.\nBugs in third-party dependencies e.g., jsoncpp, boost etc. are not in scope unless they result in a Solidity specific bug.\n\nOnly bugs that have a demonstrable security impact on smart contracts are in scope.\nFor example, a Solidity program whose optimization is incorrect (e.g., leads to an incorrect output) qualifies as a security bug.\nPlease note that the [rules][2] of the [Ethereum bounty program][1] have precedence over this security policy.\n\n## Supported Versions\n\nAs a general rule, only the latest release gets security updates.\nExceptions may be made when the current breaking release is relatively new, e.g. less than three months old.\nIf you are reporting a bug, please state clearly the Solidity version(s) it affects.\n\nExample 1: Assuming the current release is `0.6.3` and a security bug has been found in it that affects both `0.5.x` and `0.6.x` trees, we may not only patch `0.6.3` (the bug-fix release numbered `0.6.4`) but `0.5.x` as well (the bug-fix release numbered `0.5.(x+1)`).\n\nExample 2: Assuming the current release is `0.6.25` and a security bug has been found in it, we may only patch `0.6.25` (in the bug-fix release numbered `0.6.26`) even if the bug affects a previous tree such as `0.5.x`.\n\n## Reporting a Vulnerability\n\nTo report a vulnerability, please follow the instructions stated in the [Ethereum bounty program][1].\n\nIn the bug report, please include all details necessary to reproduce the vulnerability such as:\n\n- Input program that triggers the bug\n- Compiler version affected\n- Target EVM version\n- Framework/IDE if applicable\n- EVM execution environment/client if applicable\n- Operating system\n\nPlease include steps to reproduce the bug you have found in as much detail as possible.\n\nOnce we have received your bug report, we will try to reproduce it and provide a more detailed response.\nOnce the reported bug has been successfully reproduced, the Solidity team will work on a fix.\n\nThe Solidity team maintains the following JSON-formatted lists of patched security vulnerabilities:\n\n- [Summary of known security vulnerabilities][3]\n- [List of security vulnerabilities affecting a specific version of the compiler][4].\n\n\n[1]: https://bounty.ethereum.org/\n[2]: https://bounty.ethereum.org/#rules\n[3]: https://docs.soliditylang.org/en/develop/bugs.html\n[4]: https://github.com/argotorg/solidity/blob/develop/docs/bugs_by_version.json\n" }, { "path": "cmake/EthBuildInfo.cmake", "content": "function(create_build_info NAME)\n\n\t# Set build platform; to be written to BuildInfo.h\n\tset(ETH_BUILD_OS \"${CMAKE_SYSTEM_NAME}\")\n\n\tif (CMAKE_COMPILER_IS_MINGW)\n\t\tset(ETH_BUILD_COMPILER \"mingw\")\n\telseif (CMAKE_COMPILER_IS_MSYS)\n\t\tset(ETH_BUILD_COMPILER \"msys\")\n\telseif (CMAKE_COMPILER_IS_GNUCXX)\n\t\tset(ETH_BUILD_COMPILER \"g++\")\n\telseif (\"${CMAKE_CXX_COMPILER_ID}\" STREQUAL \"MSVC\")\n\t\tset(ETH_BUILD_COMPILER \"msvc\")\n\telseif (\"${CMAKE_CXX_COMPILER_ID}\" STREQUAL \"Clang\")\n\t\tset(ETH_BUILD_COMPILER \"clang\")\n\telseif (\"${CMAKE_CXX_COMPILER_ID}\" STREQUAL \"AppleClang\")\n\t\tset(ETH_BUILD_COMPILER \"appleclang\")\n\telse ()\n\t\tset(ETH_BUILD_COMPILER \"unknown\")\n\tendif ()\n\n\tset(ETH_BUILD_PLATFORM \"${ETH_BUILD_OS}.${ETH_BUILD_COMPILER}\")\n\n\t#cmake build type may be not speCified when using msvc\n\tif (CMAKE_BUILD_TYPE)\n\t\tset(_cmake_build_type ${CMAKE_BUILD_TYPE})\n\telse()\n\t\tset(_cmake_build_type \"${CMAKE_CFG_INTDIR}\")\n\tendif()\n\n\t# Generate header file containing useful build information\n\tadd_custom_target(${NAME}_BuildInfo.h ALL\n\t\tWORKING_DIRECTORY ${PROJECT_SOURCE_DIR}\n\t\tCOMMAND ${CMAKE_COMMAND} -DETH_SOURCE_DIR=${PROJECT_SOURCE_DIR} -DETH_BUILDINFO_IN=${ETH_CMAKE_DIR}/templates/BuildInfo.h.in -DETH_DST_DIR=${PROJECT_BINARY_DIR}/include/${PROJECT_NAME} -DETH_CMAKE_DIR=${ETH_CMAKE_DIR}\n\t\t-DETH_BUILD_TYPE=\"${_cmake_build_type}\"\n\t\t-DETH_BUILD_OS=\"${ETH_BUILD_OS}\"\n\t\t-DETH_BUILD_COMPILER=\"${ETH_BUILD_COMPILER}\"\n\t\t-DETH_BUILD_PLATFORM=\"${ETH_BUILD_PLATFORM}\"\n\t\t-DPROJECT_VERSION=\"${PROJECT_VERSION}\"\n\t\t-DPROJECT_VERSION_MAJOR=\"${PROJECT_VERSION_MAJOR}\"\n\t\t-DPROJECT_VERSION_MINOR=\"${PROJECT_VERSION_MINOR}\"\n\t\t-DPROJECT_VERSION_PATCH=\"${PROJECT_VERSION_PATCH}\"\n\t\t-P \"${ETH_SCRIPTS_DIR}/buildinfo.cmake\"\n\t\t)\n\tinclude_directories(\"${PROJECT_BINARY_DIR}/include\")\nendfunction()\n" }, { "path": "cmake/EthCcache.cmake", "content": "# Setup ccache.\n#\n# The ccache is auto-enabled if the tool is found.\n# To disable set -DCCACHE=OFF option.\nif(NOT DEFINED CMAKE_CXX_COMPILER_LAUNCHER)\n find_program(CCACHE ccache DOC \"ccache tool path; set to OFF to disable\")\n if(CCACHE)\n set(CMAKE_CXX_COMPILER_LAUNCHER ${CCACHE})\n if(COMMAND cotire)\n # Change ccache config to meet cotire requirements.\n set(ENV{CCACHE_SLOPPINESS} pch_defines,time_macros)\n endif()\n message(STATUS \"[ccache] Enabled: ${CCACHE}\")\n endif()\nendif()\n" }, { "path": "cmake/EthCheckCXXCompilerFlag.cmake", "content": "include(CheckCXXCompilerFlag)\n\n# Adds CXX compiler flag if the flag is supported by the compiler.\n#\n# This is effectively a combination of CMake's check_cxx_compiler_flag()\n# and add_compile_options():\n#\n# if(check_cxx_compiler_flag(flag))\n# add_compile_options(flag)\n#\nfunction(eth_add_cxx_compiler_flag_if_supported FLAG)\n # Remove leading - or / from the flag name.\n string(REGEX REPLACE \"^[-/]\" \"\" name ${FLAG})\n # Deletes any ':' because it's invalid variable names.\n string(REGEX REPLACE \":\" \"\" name ${name})\n check_cxx_compiler_flag(${FLAG} ${name})\n if(${name})\n add_compile_options(${FLAG})\n endif()\n\n # If the optional argument passed, store the result there.\n if(ARGV1)\n set(${ARGV1} ${name} PARENT_SCOPE)\n endif()\nendfunction()\n" }, { "path": "cmake/EthCompilerSettings.cmake", "content": "#------------------------------------------------------------------------------\n# EthCompilerSettings.cmake\n#\n# CMake file for cpp-ethereum project which specifies our compiler settings\n# for each supported platform and build configuration.\n#\n# The documentation for cpp-ethereum is hosted at http://cpp-ethereum.org\n#\n# Copyright (c) 2014-2016 cpp-ethereum contributors.\n#------------------------------------------------------------------------------\n\n# Clang seeks to be command-line compatible with GCC as much as possible, so\n# most of our compiler settings are common between GCC and Clang.\n#\n# These settings then end up spanning all POSIX platforms (Linux, OS X, BSD, etc)\n\ninclude(EthCheckCXXCompilerFlag)\n\nif(NOT EMSCRIPTEN)\n\teth_add_cxx_compiler_flag_if_supported(-fstack-protector-strong have_stack_protector_strong_support)\n\tif(NOT have_stack_protector_strong_support)\n\t\teth_add_cxx_compiler_flag_if_supported(-fstack-protector)\n\tendif()\nendif()\n\nif(PEDANTIC)\n\teth_add_cxx_compiler_flag_if_supported(-Wimplicit-fallthrough)\nendif()\n\n# Prevent the path of the source directory from ending up in the binary via __FILE__ macros.\neth_add_cxx_compiler_flag_if_supported(\"-fmacro-prefix-map=${PROJECT_SOURCE_DIR}=/solidity\")\n\n# -Wpessimizing-move warns when a call to std::move would prevent copy elision\n# if the argument was not wrapped in a call. This happens when moving a local\n# variable in a return statement when the variable is the same type as the\n# return type or using a move to create a new object from a temporary object.\nif(PEDANTIC)\n\teth_add_cxx_compiler_flag_if_supported(-Wpessimizing-move)\nendif()\n\n# -Wredundant-move warns when an implicit move would already be made, so the\n# std::move call is not needed, such as when moving a local variable in a return\n# that is different from the return type.\nif(PEDANTIC)\n\teth_add_cxx_compiler_flag_if_supported(-Wredundant-move)\nendif()\n\nif ((\"${CMAKE_CXX_COMPILER_ID}\" MATCHES \"GNU\") OR (\"${CMAKE_CXX_COMPILER_ID}\" MATCHES \"Clang\"))\n\t# Enables all the warnings about constructions that some users consider questionable,\n\t# and that are easy to avoid. Also enable some extra warning flags that are not\n\t# enabled by -Wall. Finally, treat at warnings-as-errors, which forces developers\n\t# to fix warnings as they arise, so they don't accumulate \"to be fixed later\".\n\tif(PEDANTIC)\n\t\tadd_compile_options(-Wall)\n\t\tadd_compile_options(-Wextra)\n\t\tadd_compile_options(-Werror)\n\t\tadd_compile_options(-pedantic)\n\t\tadd_compile_options(-Wmissing-declarations)\n\t\tadd_compile_options(-Wno-unknown-pragmas)\n\t\tadd_compile_options(-Wimplicit-fallthrough)\n\t\tadd_compile_options(-Wsign-conversion)\n\t\tadd_compile_options(-Wconversion)\n\n\t\tcheck_cxx_compiler_flag(-Wextra-semi WEXTRA_SEMI)\n\t\tif(WEXTRA_SEMI)\n\t\t\tadd_compile_options($<$:-Wextra-semi>)\n\t\tendif()\n\t\t# See https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;h=6b927b1297e66e26e62e722bf15c921dcbbd25b9\n\t\tcheck_cxx_compiler_flag(-Wno-dangling-reference WNO_DANGLING_REFERENCE)\n\t\tif (WNO_DANGLING_REFERENCE)\n add_compile_options($<$:-Wno-dangling-reference>)\n\t\tendif()\n\n\n\t\teth_add_cxx_compiler_flag_if_supported(-Wfinal-dtor-non-final-class)\n\t\teth_add_cxx_compiler_flag_if_supported(-Wnewline-eof)\n\t\teth_add_cxx_compiler_flag_if_supported(-Wsuggest-destructor-override)\n\t\teth_add_cxx_compiler_flag_if_supported(-Wduplicated-cond)\n\t\teth_add_cxx_compiler_flag_if_supported(-Wduplicate-enum)\n\t\teth_add_cxx_compiler_flag_if_supported(-Wlogical-op)\n\t\teth_add_cxx_compiler_flag_if_supported(-Wno-unknown-attributes)\n\tendif()\n\n\t# Configuration-specific compiler settings.\n\tset(CMAKE_CXX_FLAGS_DEBUG \"-O0 -g3 -DETH_DEBUG\")\n\tset(CMAKE_CXX_FLAGS_MINSIZEREL \"-Os -DNDEBUG\")\n\tset(CMAKE_CXX_FLAGS_RELEASE \"-O3 -DNDEBUG\")\n\tset(CMAKE_CXX_FLAGS_RELWITHDEBINFO \"-O2 -g3\")\n\n\t# Additional GCC-specific compiler settings.\n\tif (\"${CMAKE_CXX_COMPILER_ID}\" MATCHES \"GNU\")\n\t\t# Check that we've got GCC 11.0 or newer.\n\t\tif (NOT (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 11.0))\n\t\t\tmessage(FATAL_ERROR \"${PROJECT_NAME} requires g++ 11.0 or greater.\")\n\t\tendif ()\n\n\t\t# GCC 12 emits warnings for string concatenations with operator+ under O3\n\t\t# See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=105651\n\t\tif (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 12.0 AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 13.0)\n\t\t\tadd_compile_options(-Wno-error=restrict)\n\t\tendif ()\n\n\t\t# Use fancy colors in the compiler diagnostics\n\t\tadd_compile_options(-fdiagnostics-color)\n\n\t# Additional Clang-specific compiler settings.\n\telseif (\"${CMAKE_CXX_COMPILER_ID}\" MATCHES \"Clang\")\n\t\t# Check that we've got clang 14.0 or newer.\n\t\tif (NOT (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 14.0))\n\t\t\tmessage(FATAL_ERROR \"${PROJECT_NAME} requires clang++ 14.0 or greater.\")\n\t\tendif ()\n\n\t\t# use std::invoke_result, superseding std::result_of which has been removed in c++20\n\t\tadd_compile_definitions(BOOST_ASIO_HAS_STD_INVOKE_RESULT)\n\t\tif (\"${CMAKE_SYSTEM_NAME}\" MATCHES \"Darwin\")\n\t\t\t# Set stack size to 32MB - by default Apple's clang defines a stack size of 8MB.\n\t\t\t# Normally 16MB is enough to run all tests, but it will exceed the stack, if -DSANITIZE=address is used.\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -Wl,-stack_size -Wl,0x2000000\")\n\n\t\t\t# Boost libraries use visibility=hidden to reduce unnecessary DWARF entries.\n\t\t\t# Unless we match visibility, ld will give a warning message like:\n\t\t\t# ld: warning: direct access in function 'boost::filesystem... from file ...\n\t\t\t# means the weak symbol cannot be overridden at runtime. This was likely caused by different translation units being compiled with different visibility settings.\n\t\t\tset(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} -fvisibility=hidden\")\n\t\tendif()\n\n\t\t# Some Linux-specific Clang settings. We don't want these for OS X.\n\t\tif (\"${CMAKE_SYSTEM_NAME}\" MATCHES \"Linux\")\n\t\t\t# Use fancy colors in the compiler diagnostics\n\t\t\tadd_compile_options(-fcolor-diagnostics)\n\n\t\t\t# See \"How to silence unused command line argument error with clang without disabling it?\"\n\t\t\t# When using -Werror with clang, it transforms \"warning: argument unused during compilation\" messages\n\t\t\t# into errors, which makes sense.\n\t\t\t# http://stackoverflow.com/questions/21617158/how-to-silence-unused-command-line-argument-error-with-clang-without-disabling-i\n\t\t\tadd_compile_options(-Qunused-arguments)\n\t\telseif(EMSCRIPTEN)\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} --memory-init-file 0\")\n\t\t\t# Leave only exported symbols as public and aggressively remove others\n\t\t\tset(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} -fdata-sections -ffunction-sections -fvisibility=hidden\")\n\t\t\t# Optimisation level\n\t\t\tset(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} -O3\")\n\t\t\t# Re-enable exception catching (optimisations above -O1 disable it)\n\t\t\tset(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} -s DISABLE_EXCEPTION_CATCHING=0\")\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s DISABLE_EXCEPTION_CATCHING=0\")\n\t\t\t# Remove any code related to exit (such as atexit)\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s EXIT_RUNTIME=0\")\n\t\t\t# Remove any code related to filesystem access\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s FILESYSTEM=0\")\n\t\t\t# Allow memory growth, but disable some optimisations\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s ALLOW_MEMORY_GROWTH=1\")\n\t\t\t# Disable eval()\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s DYNAMIC_EXECUTION=0\")\n\t\t\t# Disable greedy exception catcher\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s NODEJS_CATCH_EXIT=0\")\n\t\t\t# Abort if linking results in any undefined symbols\n\t\t\t# Note: this is on by default in the CMake Emscripten module which we aren't using\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s ERROR_ON_UNDEFINED_SYMBOLS=1\")\n\t\t\t# Disallow deprecated emscripten build options.\n\t\t\tset(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} -s STRICT=1\")\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s STRICT=1\")\n\t\t\t# Export the Emscripten-generated auxiliary methods which are needed by solc-js.\n\t\t\t# Which methods of libsolc itself are exported is specified in libsolc/CMakeLists.txt.\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s EXTRA_EXPORTED_RUNTIME_METHODS=['cwrap','addFunction','removeFunction','UTF8ToString','lengthBytesUTF8','stringToUTF8','setValue']\")\n\t\t\t# Build for webassembly target.\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s WASM=1\")\n\t\t\t# Set webassembly build to synchronous loading.\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s WASM_ASYNC_COMPILATION=0\")\n\t\t\t# Allow new functions to be added to the wasm module via addFunction.\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s ALLOW_TABLE_GROWTH=1\")\n\t\t\t# Disable warnings about not being pure asm.js due to memory growth.\n\t\t\tset(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} -Wno-almost-asm\")\n\t\t\t# Increase stack size from 5MB to 16MB to prevent stack overflow issues.\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s TOTAL_STACK=16mb\")\n\t\t\t# Increase memory size from 16MB to 32MB since the stack size is now 16MB.\n\t\t\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} -s INITIAL_MEMORY=32mb\")\n\t\tendif()\n\tendif()\n\n# The major alternative compiler to GCC/Clang is Microsoft's Visual C++ compiler, only available on Windows.\nelseif (DEFINED MSVC)\n\t# Remove NDEBUG from RELWITHDEBINFO (to enable asserts)\n\t# CMAKE_CXX_FLAGS_RELWITHDEBINFO for GCC/Clang does not include NDEBUG\n\tstring(REPLACE \"/DNDEBUG\" \" \" CMAKE_CXX_FLAGS_RELWITHDEBINFO \"${CMAKE_CXX_FLAGS_RELWITHDEBINFO}\")\n\n\tadd_compile_options(/MP) # enable parallel compilation\n\tadd_compile_options(/EHsc) # specify Exception Handling Model in msvc\n\tif(PEDANTIC)\n\t\tadd_compile_options(/WX) # enable warnings-as-errors\n\tendif()\n\tadd_compile_options(/wd4068) # disable unknown pragma warning (4068)\n\tadd_compile_options(/wd4996) # disable unsafe function warning (4996)\n\tadd_compile_options(/wd4503) # disable decorated name length exceeded, name was truncated (4503)\n\tadd_compile_options(/wd4267) # disable conversion from 'size_t' to 'type', possible loss of data (4267)\n\tadd_compile_options(/wd4180) # disable qualifier applied to function type has no meaning; ignored (4180)\n\tadd_compile_options(/wd4290) # disable C++ exception specification ignored except to indicate a function is not __declspec(nothrow) (4290)\n\tadd_compile_options(/wd4244) # disable conversion from 'type1' to 'type2', possible loss of data (4244)\n\tadd_compile_options(/wd4800) # disable forcing value to bool 'true' or 'false' (performance warning) (4800)\n\tadd_compile_options(-D_WIN32_WINNT=0x0600) # declare Windows Vista API requirement\n\tadd_compile_options(-DNOMINMAX) # undefine windows.h MAX && MIN macros cause it cause conflicts with std::min && std::max functions\n\tadd_compile_options(/utf-8) # enable utf-8 encoding (solves warning 4819)\n\tadd_compile_options(-DBOOST_REGEX_NO_LIB) # disable automatic boost::regex library selection\n\tadd_compile_options(-D_REGEX_MAX_STACK_COUNT=200000L) # increase std::regex recursion depth limit\n\tadd_compile_options(/permissive-) # specify standards conformance mode to the compiler\n\n\t# disable empty object file warning\n\tset(CMAKE_STATIC_LINKER_FLAGS \"${CMAKE_STATIC_LINKER_FLAGS} /ignore:4221\")\n\t# warning LNK4075: ignoring '/EDITANDCONTINUE' due to '/SAFESEH' specification\n\t# warning LNK4099: pdb was not found with lib\n\t# stack size 16MB\n\tset(CMAKE_EXE_LINKER_FLAGS \"${CMAKE_EXE_LINKER_FLAGS} /ignore:4099,4075 /STACK:16777216\")\n\n# If you don't have GCC, Clang or VC++ then you are on your own. Good luck!\nelse ()\n\tmessage(WARNING \"Your compiler is not tested, if you run into any issues, we'd welcome any patches.\")\nendif ()\n\nif (SANITIZE)\n\t# Perform case-insensitive string compare\n\tstring(TOLOWER \"${SANITIZE}\" sanitizer)\n\t# -fno-omit-frame-pointer gives more informative stack trace in case of an error\n\t# -fsanitize-address-use-after-scope throws an error when a variable is used beyond its scope\n\tif (sanitizer STREQUAL \"address\")\n\t\tset(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} -fno-omit-frame-pointer -fsanitize=address -fsanitize-address-use-after-scope\")\n\telseif (sanitizer STREQUAL \"undefined\")\n\t\t# The following flags not used by fuzzer but used by us may create problems, so consider\n\t\t# disabling them: alignment, pointer-overflow.\n\t\t# The following flag is not used by us to reduce terminal noise\n\t\t# i.e., warnings printed on stderr: unsigned-integer-overflow\n\t\t# Note: The C++ standard does not officially consider unsigned integer overflows\n\t\t# to be undefined behavior since they are implementation independent.\n\t\t# Flags are alphabetically sorted and are for clang v10.0\n\t\tlist(APPEND undefinedSanitizerChecks\n\t\t\talignment\n\t\t\tarray-bounds\n\t\t\tbool\n\t\t\tbuiltin\n\t\t\tenum\n\t\t\tfloat-divide-by-zero\n\t\t\tfunction\n\t\t\tinteger-divide-by-zero\n\t\t\tnull\n\t\t\tobject-size\n\t\t\tpointer-overflow\n\t\t\treturn\n\t\t\treturns-nonnull-attribute\n\t\t\tshift\n\t\t\tsigned-integer-overflow\n\t\t\tunreachable\n\t\t\tvla-bound\n\t\t\tvptr\n\t\t)\n\t\tlist(JOIN undefinedSanitizerChecks \",\" sanitizerChecks)\n\t\tset(CMAKE_CXX_FLAGS \"${CMAKE_CXX_FLAGS} -fsanitize=${sanitizerChecks} -fno-sanitize-recover=${sanitizerChecks}\")\n\tendif()\nendif()\n\n# Code coverage support.\n# Copied from Cable:\n# https://github.com/ethereum/cable/blob/v0.2.4/CableCompilerSettings.cmake#L118-L132\noption(COVERAGE \"Build with code coverage support\" OFF)\nif(COVERAGE)\n\t# Set the linker flags first, they are required to properly test the compiler flag.\n\tset(CMAKE_SHARED_LINKER_FLAGS \"--coverage ${CMAKE_SHARED_LINKER_FLAGS}\")\n\tset(CMAKE_EXE_LINKER_FLAGS \"--coverage ${CMAKE_EXE_LINKER_FLAGS}\")\n\n\tset(CMAKE_REQUIRED_LIBRARIES \"--coverage ${CMAKE_REQUIRED_LIBRARIES}\")\n\tcheck_cxx_compiler_flag(--coverage have_coverage)\n\tstring(REPLACE \"--coverage \" \"\" CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})\n\tif(NOT have_coverage)\n\t\tmessage(FATAL_ERROR \"Coverage not supported\")\n\tendif()\n\tadd_compile_options(-g --coverage)\nendif()\n" }, { "path": "cmake/EthDependencies.cmake", "content": "# all dependencies that are not directly included in the cpp-ethereum distribution are defined here\n# for this to work, download the dependency via the cmake script in extdep or install them manually!\n\nif (DEFINED MSVC)\n\t# by defining CMAKE_PREFIX_PATH variable, cmake will look for dependencies first in our own repository before looking in system paths like /usr/local/ ...\n\t# this must be set to point to the same directory as $ETH_DEPENDENCY_INSTALL_DIR in /extdep directory\n\n\tif (CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.0.0)\n\t\tset (ETH_DEPENDENCY_INSTALL_DIR \"${CMAKE_CURRENT_LIST_DIR}/../extdep/install/windows/x64\")\n\telse()\n\t\tget_filename_component(DEPS_DIR \"${CMAKE_CURRENT_LIST_DIR}/../deps/install\" ABSOLUTE)\n\t\tset(ETH_DEPENDENCY_INSTALL_DIR\n\t\t\t\"${DEPS_DIR}/x64\" # Old location for deps.\n\t\t\t\"${DEPS_DIR}/win64\" # New location for deps.\n\t\t\t\"${DEPS_DIR}/win64/Release/share\" # LLVM shared cmake files.\n\t\t)\n\tendif()\n\tset (CMAKE_PREFIX_PATH ${ETH_DEPENDENCY_INSTALL_DIR} ${CMAKE_PREFIX_PATH})\nendif()\n\n# custom cmake scripts\nset(ETH_CMAKE_DIR ${CMAKE_CURRENT_LIST_DIR})\nset(ETH_SCRIPTS_DIR ${ETH_CMAKE_DIR}/scripts)\n\n## use multithreaded boost libraries, with -mt suffix\nset(Boost_USE_MULTITHREADED ON)\noption(Boost_USE_STATIC_LIBS \"Link Boost statically\" ON)\nif (WIN32)\n\toption(Boost_USE_STATIC_RUNTIME \"Link Boost against static C++ runtime libraries\" ON)\nendif()\n\nset(BOOST_COMPONENTS \"filesystem;unit_test_framework;program_options\")\n\n# CMake >= 3.30 should not use the vendored boost\nif(POLICY CMP0167)\n\tcmake_policy(SET CMP0167 NEW)\nendif()\nif (WIN32)\n\t# Boost 1.77 fixes a bug that causes crashes on Windows for some relative paths in --allow-paths.\n\t# See https://github.com/boostorg/filesystem/issues/201\n\tfind_package(Boost 1.77.0 QUIET REQUIRED COMPONENTS ${BOOST_COMPONENTS})\nelse()\n\t# Boost 1.65 is the first to also provide boost::get for rvalue-references (#5787).\n\t# Boost 1.67 moved container_hash into is own module.\n\t# Boost 1.69 boost::system is header-only and no longer needs to be fetched as component\n\t# Boost 1.70 comes with its own BoostConfig.cmake and is the new (non-deprecated) behavior\n\t# Boost 1.75 fixes infinite recursion on `boost::rational` comparison with GCC<14.0 under C++20\n\t# Boost 1.83 is the version that comes with Ubuntu 24.04.\n\tfind_package(Boost 1.83.0 QUIET REQUIRED COMPONENTS ${BOOST_COMPONENTS})\nendif()\n\n# If cmake is older than boost and boost is older than 1.70,\n# find_package does not define imported targets, so we have to\n# define them manually.\n\nif (NOT TARGET Boost::boost) # header only target\n\tadd_library(Boost::boost INTERFACE IMPORTED)\n\tset_property(TARGET Boost::boost APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES ${Boost_INCLUDE_DIRS})\nendif()\nmessage(STATUS \"Found Boost ${Boost_VERSION} headers in ${Boost_INCLUDE_DIRS}\")\n\nforeach (BOOST_COMPONENT IN LISTS BOOST_COMPONENTS)\n\tif (NOT TARGET Boost::${BOOST_COMPONENT})\n\t\tadd_library(Boost::${BOOST_COMPONENT} UNKNOWN IMPORTED)\n\t\tstring(TOUPPER ${BOOST_COMPONENT} BOOST_COMPONENT_UPPER)\n\t\tset_property(TARGET Boost::${BOOST_COMPONENT} PROPERTY IMPORTED_LOCATION ${Boost_${BOOST_COMPONENT_UPPER}_LIBRARY})\n\t\tset_property(TARGET Boost::${BOOST_COMPONENT} PROPERTY INTERFACE_LINK_LIBRARIES ${Boost_${BOOST_COMPONENT_UPPER}_LIBRARIES})\n\t\tset_property(TARGET Boost::${BOOST_COMPONENT} PROPERTY INTERFACE_INCLUDE_DIRECTORIES ${Boost_INCLUDE_DIRS})\n\tendif()\n\tget_property(LOCATION TARGET Boost::${BOOST_COMPONENT} PROPERTY IMPORTED_LOCATION)\n\tmessage(STATUS \"Found Boost::${BOOST_COMPONENT} at ${LOCATION}\")\nendforeach()\n" }, { "path": "cmake/EthOptions.cmake", "content": "# CMAKE macros to set default CMAKE options and to show the\n# resulting configuration.\n\nmacro(configure_project)\n\tset(NAME ${PROJECT_NAME})\n\n\t# features\n\teth_default_option(COVERAGE OFF)\n\teth_default_option(OSSFUZZ OFF)\n\n\t# components\n\teth_default_option(TESTS ON)\n\teth_default_option(TOOLS ON)\n\n\t# Define a matching property name of each of the \"features\".\n\tforeach(FEATURE ${ARGN})\n\t\tset(SUPPORT_${FEATURE} TRUE)\n\tendforeach()\n\n\tinclude(EthBuildInfo)\n\tcreate_build_info(${NAME})\n\tprint_config(${NAME})\nendmacro()\n\nmacro(print_config NAME)\n\tmessage(\"\")\n\tmessage(\"------------------------------------------------------------------------\")\n\tmessage(\"-- Configuring ${NAME} ${PROJECT_VERSION}\")\n\tmessage(\"------------------------------------------------------------------------\")\n\tmessage(\"-- CMake Version ${CMAKE_VERSION}\")\n\tmessage(\"-- CMAKE_BUILD_TYPE Build type ${CMAKE_BUILD_TYPE}\")\n\tmessage(\"-- TARGET_PLATFORM Target platform ${CMAKE_SYSTEM_NAME}\")\n\tmessage(\"--------------------------------------------------------------- features\")\n\tmessage(\"-- COVERAGE Coverage support ${COVERAGE}\")\n\tmessage(\"------------------------------------------------------------- components\")\nif (SUPPORT_TESTS)\n\tmessage(\"-- TESTS Build tests ${TESTS}\")\nendif()\nif (SUPPORT_TOOLS)\n\tmessage(\"-- TOOLS Build tools ${TOOLS}\")\nendif()\n\tmessage(\"------------------------------------------------------------------ flags\")\n\tmessage(\"-- OSSFUZZ ${OSSFUZZ}\")\n\tmessage(\"------------------------------------------------------------------------\")\n\tmessage(\"\")\nendmacro()\n" }, { "path": "cmake/EthPolicy.cmake", "content": "# it must be a macro cause policies have scopes\n# http://www.cmake.org/cmake/help/v3.0/command/cmake_policy.html\nmacro (eth_policy)\n\t# link_directories() treats paths relative to the source dir.\n\tcmake_policy(SET CMP0015 NEW)\n\n\t# Avoid warnings in CMake 3.0.2:\n\tcmake_policy(SET CMP0042 NEW)\n\tcmake_policy(SET CMP0043 NEW)\n\n\t# allow VERSION argument in project()\n\tcmake_policy(SET CMP0048 NEW)\n\n\tif (POLICY CMP0054)\n\t\t# do not interpret if() arguments as variables!\n\t\tcmake_policy(SET CMP0054 NEW)\n\tendif()\n\n\tif (POLICY CMP0091)\n\t\t# Allow selecting MSVC runtime library using CMAKE_MSVC_RUNTIME_LIBRARY.\n\t\tcmake_policy(SET CMP0091 NEW)\n\tendif()\n\n\t# Avoid warning about DOWNLOAD_EXTRACT_TIMESTAMP in CMake 3.24:\n\tif (CMAKE_VERSION VERSION_GREATER_EQUAL \"3.24.0\")\n\t\tcmake_policy(SET CMP0135 NEW)\n\tendif()\n\n\tif(POLICY CMP0115)\n\t\t# Require explicit extensions for source files, do not guess.\n\t\t# The extra calls to GetFileAttributesW significantly slow down cmake on Windows.\n\t\t# https://gitlab.kitware.com/cmake/cmake/-/issues/23154\n\t\tcmake_policy(SET CMP0115 NEW)\n\tendif()\nendmacro()\n" }, { "path": "cmake/EthToolchains.cmake", "content": "# Require C++20.\nif (NOT DEFINED CMAKE_CXX_STANDARD)\n set(CMAKE_CXX_STANDARD 20) # This requires at least CMake 3.12 to accept this C++20 flag.\nendif ()\nset(CMAKE_CXX_STANDARD_REQUIRED TRUE)\nset(CMAKE_CXX_EXTENSIONS OFF)\n\nif(NOT CMAKE_TOOLCHAIN_FILE)\n # Use default toolchain file if none is provided.\n set(\n CMAKE_TOOLCHAIN_FILE\n \"${CMAKE_CURRENT_LIST_DIR}/toolchains/default.cmake\"\n CACHE FILEPATH \"The CMake toolchain file\"\n )\nendif()\n" }, { "path": "cmake/EthUtils.cmake", "content": "#\n# renames the file if it is different from its destination\ninclude(CMakeParseArguments)\n#\nmacro(replace_if_different SOURCE DST)\n\tset(extra_macro_args ${ARGN})\n\tset(options CREATE)\n\tset(one_value_args)\n\tset(multi_value_args)\n\tcmake_parse_arguments(REPLACE_IF_DIFFERENT \"${options}\" \"${one_value_args}\" \"${multi_value_args}\" \"${extra_macro_args}\")\n\n\tif (REPLACE_IF_DIFFERENT_CREATE AND (NOT (EXISTS \"${DST}\")))\n\t\tfile(WRITE \"${DST}\" \"\")\n\tendif()\n\n\texecute_process(COMMAND ${CMAKE_COMMAND} -E compare_files \"${SOURCE}\" \"${DST}\" RESULT_VARIABLE DIFFERENT OUTPUT_QUIET ERROR_QUIET)\n\n\tif (DIFFERENT)\n\t\texecute_process(COMMAND ${CMAKE_COMMAND} -E rename \"${SOURCE}\" \"${DST}\")\n\telse()\n\t\texecute_process(COMMAND ${CMAKE_COMMAND} -E remove \"${SOURCE}\")\n\tendif()\nendmacro()\n\nmacro(eth_default_option O DEF)\n\tif (DEFINED ${O})\n\t\tif (${${O}})\n\t\t\tset(${O} ON)\n\t\telse ()\n\t\t\tset(${O} OFF)\n\t\tendif()\n\telse ()\n\t\tset(${O} ${DEF})\n\tendif()\nendmacro()\n\nfunction(detect_stray_source_files FILELIST DIRECTORY)\n\tif(CMAKE_VERSION VERSION_LESS 3.12)\n\t\tfile(GLOB sources RELATIVE \"${CMAKE_CURRENT_SOURCE_DIR}\" \"${DIRECTORY}/*.cpp\" \"${DIRECTORY}/*.h\")\n\telse()\n\t\tfile(GLOB sources RELATIVE \"${CMAKE_CURRENT_SOURCE_DIR}\" CONFIGURE_DEPENDS \"${DIRECTORY}/*.cpp\" \"${DIRECTORY}/*.h\")\n\tendif()\n\tforeach(path IN LISTS FILELIST)\n\t\tlist(REMOVE_ITEM sources ${path})\n\tendforeach()\n\tlist(LENGTH sources leftover_sources)\n\tif (leftover_sources)\n\t\tmessage(SEND_ERROR \"The following source files are present but are not compiled: ${sources}\")\n\tendif()\nendfunction(detect_stray_source_files)\n\n# CreateExportedFunctionsForEMSDK(OUTPUT_VARIABLE Symbol1 Symbol2 ... SymbolN)\nfunction(CreateExportedFunctionsForEMSDK OUTPUT_VARIABLE)\n\tlist(TRANSFORM ARGN PREPEND \"\\\"_\")\n\tlist(TRANSFORM ARGN APPEND \"\\\"\")\n\tlist(JOIN ARGN \",\" ARGN)\n\tset(${OUTPUT_VARIABLE} \"[${ARGN}]\" PARENT_SCOPE)\nendfunction()\n" }, { "path": "cmake/FindCLN.cmake", "content": "find_library(CLN_LIBRARY NAMES cln)\ninclude(FindPackageHandleStandardArgs)\nfind_package_handle_standard_args(CLN DEFAULT_MSG CLN_LIBRARY)\n\nif(CLN_FOUND AND NOT TARGET CLN::CLN)\n add_library(CLN::CLN UNKNOWN IMPORTED)\n set_property(TARGET CLN::CLN PROPERTY IMPORTED_LOCATION ${CLN_LIBRARY})\nendif()\n" }, { "path": "cmake/FindGMP.cmake", "content": "find_library(GMP_LIBRARY NAMES gmp)\ninclude(FindPackageHandleStandardArgs)\nfind_package_handle_standard_args(GMP DEFAULT_MSG GMP_LIBRARY)\n\nif(GMP_FOUND AND NOT TARGET GMP::GMP)\n add_library(GMP::GMP UNKNOWN IMPORTED)\n set_property(TARGET GMP::GMP PROPERTY IMPORTED_LOCATION ${GMP_LIBRARY})\nendif()\n" }, { "path": "cmake/FindZ3.cmake", "content": "# Save and clear Z3_FIND_VERSION, since the\n# Z3 config module cannot handle version requirements.\nset(Z3_FIND_VERSION_ORIG ${Z3_FIND_VERSION})\nset(Z3_FIND_VERSION)\n# Try to find Z3 using its stock cmake files.\nfind_package(Z3 QUIET CONFIG)\n# Restore Z3_FIND_VERSION for find_package_handle_standard_args.\nset(Z3_FIND_VERSION ${Z3_FIND_VERSION_ORIG})\nset(Z3_FIND_VERSION_ORIG)\n\ninclude(FindPackageHandleStandardArgs)\n\nif (Z3_FOUND)\n set(Z3_VERSION ${Z3_VERSION_STRING})\n find_package_handle_standard_args(Z3 CONFIG_MODE)\nelse()\n find_path(Z3_INCLUDE_DIR NAMES z3++.h PATH_SUFFIXES z3)\n find_library(Z3_LIBRARY NAMES z3)\n find_program(Z3_EXECUTABLE z3 PATH_SUFFIXES bin)\n\n if(Z3_INCLUDE_DIR AND Z3_LIBRARY)\n if(Z3_EXECUTABLE)\n execute_process (COMMAND ${Z3_EXECUTABLE} -version\n OUTPUT_VARIABLE libz3_version_str\n ERROR_QUIET\n OUTPUT_STRIP_TRAILING_WHITESPACE)\n\n string(REGEX REPLACE \"^Z3 version ([0-9.]+).*\" \"\\\\1\"\n Z3_VERSION_STRING \"${libz3_version_str}\")\n unset(libz3_version_str)\n else()\n message(WARNING \"Could not determine the version of z3, since the z3 executable was not found.\")\n set(Z3_VERSION_STRING \"0.0.0\")\n endif()\n endif()\n mark_as_advanced(Z3_VERSION_STRING z3_DIR)\n\n find_package_handle_standard_args(Z3\n REQUIRED_VARS Z3_LIBRARY Z3_INCLUDE_DIR\n VERSION_VAR Z3_VERSION_STRING)\n\n if (NOT TARGET z3::libz3)\n add_library(z3::libz3 UNKNOWN IMPORTED)\n set_property(TARGET z3::libz3 PROPERTY IMPORTED_LOCATION ${Z3_LIBRARY})\n set_property(TARGET z3::libz3 PROPERTY INTERFACE_INCLUDE_DIRECTORIES ${Z3_INCLUDE_DIR})\n endif()\nendif()\n" }, { "path": "cmake/fmtlib.cmake", "content": "include(${CMAKE_SOURCE_DIR}/cmake/submodules.cmake)\ninitialize_submodule(fmtlib)\n\nset(FMT_SYSTEM_HEADERS ON)\nadd_subdirectory(\n\t${CMAKE_SOURCE_DIR}/deps/fmtlib\n\tEXCLUDE_FROM_ALL\n)\n\n" }, { "path": "cmake/nlohmann-json.cmake", "content": "include(${CMAKE_SOURCE_DIR}/cmake/submodules.cmake)\ninitialize_submodule(nlohmann-json)\n\nset(JSON_Install OFF CACHE INTERNAL \"\")\nadd_subdirectory(\n\t${CMAKE_SOURCE_DIR}/deps/nlohmann-json\n\tEXCLUDE_FROM_ALL\n)\n\n" }, { "path": "cmake/range-v3.cmake", "content": "include(${CMAKE_SOURCE_DIR}/cmake/submodules.cmake)\ninitialize_submodule(range-v3)\n\nadd_library(range-v3 INTERFACE IMPORTED)\nset_target_properties(range-v3 PROPERTIES\n\tINTERFACE_COMPILE_OPTIONS \"\\$<\\$:/permissive->\"\n\tINTERFACE_SYSTEM_INCLUDE_DIRECTORIES ${CMAKE_SOURCE_DIR}/deps/range-v3/include\n\tINTERFACE_INCLUDE_DIRECTORIES ${CMAKE_SOURCE_DIR}/deps/range-v3/include\n)\nadd_dependencies(range-v3 range-v3-project)\n\n" }, { "path": "cmake/scripts/buildinfo.cmake", "content": "# generates BuildInfo.h\n#\n# this module expects\n# ETH_SOURCE_DIR - main CMAKE_SOURCE_DIR\n# ETH_DST_DIR - main CMAKE_BINARY_DIR\n# ETH_BUILD_TYPE\n# ETH_BUILD_PLATFORM\n#\n# example usage:\n# cmake -DETH_SOURCE_DIR=. -DETH_DST_DIR=build -DETH_BUILD_TYPE=Debug -DETH_BUILD_PLATFORM=Darwin.appleclang -P scripts/buildinfo.cmake\n#\n# Its main output variables are SOL_VERSION_BUILDINFO and SOL_VERSION_PRERELEASE\n\nif (NOT ETH_BUILD_TYPE)\n\tset(ETH_BUILD_TYPE \"unknown\")\nendif()\n\nif (NOT ETH_BUILD_PLATFORM)\n\tset(ETH_BUILD_PLATFORM \"unknown\")\nendif()\n\n# Logic here: If prerelease.txt exists but is empty, it is a non-pre release.\n# If it does not exist, create our own prerelease string\nif (EXISTS ${ETH_SOURCE_DIR}/prerelease.txt)\n\tfile(READ ${ETH_SOURCE_DIR}/prerelease.txt SOL_VERSION_PRERELEASE)\n\tstring(STRIP \"${SOL_VERSION_PRERELEASE}\" SOL_VERSION_PRERELEASE)\nelse()\n\tstring(TIMESTAMP SOL_VERSION_PRERELEASE \"develop.%Y.%m.%d\" UTC)\n\tstring(REPLACE .0 . SOL_VERSION_PRERELEASE \"${SOL_VERSION_PRERELEASE}\")\nendif()\n\nif (EXISTS ${ETH_SOURCE_DIR}/commit_hash.txt)\n\tfile(READ ${ETH_SOURCE_DIR}/commit_hash.txt SOL_COMMIT_HASH)\n\tstring(STRIP ${SOL_COMMIT_HASH} SOL_COMMIT_HASH)\nelse()\n\texecute_process(\n\t\tCOMMAND git --git-dir=${ETH_SOURCE_DIR}/.git --work-tree=${ETH_SOURCE_DIR} rev-parse --short=8 HEAD\n\t\tOUTPUT_VARIABLE SOL_COMMIT_HASH OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET\n\t)\n\texecute_process(\n\t\tCOMMAND git --git-dir=${ETH_SOURCE_DIR}/.git --work-tree=${ETH_SOURCE_DIR} diff HEAD --shortstat\n\t\tOUTPUT_VARIABLE SOL_LOCAL_CHANGES OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET\n\t)\nendif()\n\nif (SOL_COMMIT_HASH)\n\tstring(STRIP ${SOL_COMMIT_HASH} SOL_COMMIT_HASH)\n\tstring(SUBSTRING ${SOL_COMMIT_HASH} 0 8 SOL_COMMIT_HASH)\nendif()\n\nif (NOT SOL_COMMIT_HASH)\n\tmessage(FATAL_ERROR \"Unable to determine commit hash. Either compile from within git repository or \"\n\t\t\"supply a file called commit_hash.txt\")\nendif()\nif (NOT SOL_COMMIT_HASH MATCHES [a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9])\n message(FATAL_ERROR \"Malformed commit hash \\\"${SOL_COMMIT_HASH}\\\". It has to consist of exactly 8 hex digits.\")\nendif()\n\nif (SOL_COMMIT_HASH AND SOL_LOCAL_CHANGES)\n\tset(SOL_COMMIT_HASH \"${SOL_COMMIT_HASH}.mod\")\nendif()\n\nset(SOL_VERSION_COMMIT \"commit.${SOL_COMMIT_HASH}\")\nset(SOL_VERSION_PLATFORM ETH_BUILD_PLATFORM)\nset(SOL_VERSION_BUILDINFO \"commit.${SOL_COMMIT_HASH}.${ETH_BUILD_PLATFORM}\")\n\nset(TMPFILE \"${ETH_DST_DIR}/BuildInfo.h.tmp\")\nset(OUTFILE \"${ETH_DST_DIR}/BuildInfo.h\")\n\nconfigure_file(\"${ETH_BUILDINFO_IN}\" \"${TMPFILE}\")\n\ninclude(\"${ETH_CMAKE_DIR}/EthUtils.cmake\")\nreplace_if_different(\"${TMPFILE}\" \"${OUTFILE}\" CREATE)\n\n" }, { "path": "cmake/submodules.cmake", "content": "macro(initialize_submodule SUBMODULE_PATH)\n\tif(NOT IGNORE_VENDORED_DEPENDENCIES)\n\t\tfile(GLOB submodule_contents \"${CMAKE_SOURCE_DIR}/deps/${SUBMODULE_PATH}/*\")\n\n\t\tif(submodule_contents)\n\t\t\tmessage(STATUS \"git submodule '${SUBMODULE_PATH}' seem to be already initialized: nothing to do.\")\n\t\telse()\n\t\t\tmessage(STATUS \"git submodule '${SUBMODULE_PATH}' seem not to be initialized: implicitly executing 'git submodule update --init '${CMAKE_SOURCE_DIR}/deps/${SUBMODULE_PATH}'.\")\n\t\t\tfind_package(Git)\n\t\t\tif(NOT Git_FOUND)\n\t\t\t\tmessage(FATAL_ERROR \"Failed to initialize submodules: 'git' command not found.\")\n\t\t\tendif()\n\t\t\texecute_process(\n\t\t\t\t\tCOMMAND git submodule update --init ${CMAKE_SOURCE_DIR}/deps/${SUBMODULE_PATH}\n\t\t\t\t\tWORKING_DIRECTORY ${CMAKE_SOURCE_DIR}\n\t\t\t\t\tRESULT_VARIABLE result\n\t\t\t)\n\t\t\tif(NOT result EQUAL 0)\n\t\t\t\tmessage(FATAL_ERROR \"Failed to initialize submodules: 'git submodule update --init' failed.\")\n\t\t\tendif()\n\t\tendif()\n\tendif()\nendmacro()\n" }, { "path": "cmake/templates/BuildInfo.h.in", "content": "#pragma once\n\n#define ETH_PROJECT_VERSION \"@PROJECT_VERSION@\"\n#define ETH_PROJECT_VERSION_MAJOR @PROJECT_VERSION_MAJOR@\n#define ETH_PROJECT_VERSION_MINOR @PROJECT_VERSION_MINOR@\n#define ETH_PROJECT_VERSION_PATCH @PROJECT_VERSION_PATCH@\n#define SOL_COMMIT_HASH \"@SOL_COMMIT_HASH@\"\n#define ETH_BUILD_TYPE \"@ETH_BUILD_TYPE@\"\n#define ETH_BUILD_OS \"@ETH_BUILD_OS@\"\n#define ETH_BUILD_COMPILER \"@ETH_BUILD_COMPILER@\"\n#define ETH_BUILD_PLATFORM \"@ETH_BUILD_PLATFORM@\"\n#define SOL_VERSION_PRERELEASE \"@SOL_VERSION_PRERELEASE@\"\n#define SOL_VERSION_BUILDINFO \"@SOL_VERSION_BUILDINFO@\"\n#define SOL_VERSION_COMMIT \"@SOL_VERSION_COMMIT@\"\n#define SOL_VERSION_PLATFORM \"@SOL_VERSION_PLATFORM@\"\n" }, { "path": "cmake/templates/license.h.in", "content": "#pragma once\n\n#include \n\nstatic std::string const otherLicenses{R\"(Most of the code is licensed under GPLv3 (see below), the license for individual\nparts and dependencies are as follows:\n\nlibkeccak-tiny:\n The file libsolutil/Keccak256.cpp incorporates libkeccak-tiny.\n\n A single-file implementation of SHA-3 and SHAKE implemented by David Leon Gil\n License: CC0, attribution kindly requested. Blame taken too, but not liability.\n\nnlohmann-json:\n The source code of nlohmann-json is licensed under the following\n conditions:\n\n The class is licensed under the MIT License:\n\n Copyright © 2013-2022 Niels Lohmann\n\n Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\n The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\n THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n The class contains the UTF-8 Decoder from Bjoern Hoehrmann which is licensed under the MIT License (see above). Copyright © 2008-2009 Björn Hoehrmann bjoern@hoehrmann.de\n\n The class contains a slightly modified version of the Grisu2 algorithm from Florian Loitsch which is licensed under the MIT License (see above). Copyright © 2009 Florian Loitsch\n\n The class contains a copy of Hedley from Evan Nemerson which is licensed as CC0-1.0.\n\npicosha2:\n The file libsolutil/picosha2.h is imported.\n\n Copyright (C) 2017 okdshin\n\n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n\n The above copyright notice and this permission notice shall be included in\n all copies or substantial portions of the Software.\n\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\n THE SOFTWARE.\n\nrange-v3:\n The range-v3 library is licensed under the following conditions:\n\n ========================================================\n Boost Software License - Version 1.0 - August 17th, 2003\n ========================================================\n\n Permission is hereby granted, free of charge, to any person or organization\n obtaining a copy of the software and accompanying documentation covered by\n this license (the \"Software\") to use, reproduce, display, distribute,\n execute, and transmit the Software, and to prepare derivative works of the\n Software, and to permit third-parties to whom the Software is furnished to\n do so, all subject to the following:\n\n The copyright notices in the Software and this entire statement, including\n the above license grant, this restriction and the following disclaimer,\n must be included in all copies of the Software, in whole or in part, and\n all derivative works of the Software, unless such copies or derivative\n works are solely in the form of machine-executable object code generated by\n a source language processor.\n\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT\n SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE\n FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,\n ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\n DEALINGS IN THE SOFTWARE.\n\n ==============================================================================\n libc++ License\n ==============================================================================\n\n The libc++ library is dual licensed under both the University of Illinois\n \"BSD-Like\" license and the MIT license. As a user of this code you may choose\n to use it under either license. As a contributor, you agree to allow your code\n to be used under both.\n\n Full text of the relevant licenses is included below.\n\n ==============================================================================\n\n University of Illinois/NCSA\n Open Source License\n\n Copyright (c) 2009-2014 by the contributors listed in CREDITS.TXT\n http://llvm.org/svn/llvm-project/libcxx/trunk/CREDITS.TXT\n\n All rights reserved.\n\n Developed by:\n\n LLVM Team\n\n University of Illinois at Urbana-Champaign\n\n http://llvm.org\n\n Permission is hereby granted, free of charge, to any person obtaining a copy of\n this software and associated documentation files (the \"Software\"), to deal with\n the Software without restriction, including without limitation the rights to\n use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\n of the Software, and to permit persons to whom the Software is furnished to do\n so, subject to the following conditions:\n\n * Redistributions of source code must retain the above copyright notice,\n this list of conditions and the following disclaimers.\n\n * Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimers in the\n documentation and/or other materials provided with the distribution.\n\n * Neither the names of the LLVM Team, University of Illinois at\n Urbana-Champaign, nor the names of its contributors may be used to\n endorse or promote products derived from this Software without specific\n prior written permission.\n\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\n FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE\n SOFTWARE.\n\n ==============================================================================\n\n Copyright (c) 2009-2014 by the contributors listed in CREDITS.TXT\n http://llvm.org/svn/llvm-project/libcxx/trunk/CREDITS.TXT\n\n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n\n The above copyright notice and this permission notice shall be included in\n all copies or substantial portions of the Software.\n\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\n THE SOFTWARE.\n\n ==============================================================================\n Stepanov and McJones, \"Elements of Programming\" license\n ==============================================================================\n\n // Copyright (c) 2009 Alexander Stepanov and Paul McJones\n //\n // Permission to use, copy, modify, distribute and sell this software\n // and its documentation for any purpose is hereby granted without\n // fee, provided that the above copyright notice appear in all copies\n // and that both that copyright notice and this permission notice\n // appear in supporting documentation. The authors make no\n // representations about the suitability of this software for any\n // purpose. It is provided \"as is\" without express or implied\n // warranty.\n //\n // Algorithms from\n // Elements of Programming\n // by Alexander Stepanov and Paul McJones\n // Addison-Wesley Professional, 2009\n\n ==============================================================================\n SGI C++ Standard Template Library license\n ==============================================================================\n\n // Copyright (c) 1994\n // Hewlett-Packard Company\n //\n // Permission to use, copy, modify, distribute and sell this software\n // and its documentation for any purpose is hereby granted without fee,\n // provided that the above copyright notice appear in all copies and\n // that both that copyright notice and this permission notice appear\n // in supporting documentation. Hewlett-Packard Company makes no\n // representations about the suitability of this software for any\n // purpose. It is provided \"as is\" without express or implied warranty.\n //\n // Copyright (c) 1996\n // Silicon Graphics Computer Systems, Inc.\n //\n // Permission to use, copy, modify, distribute and sell this software\n // and its documentation for any purpose is hereby granted without fee,\n // provided that the above copyright notice appear in all copies and\n // that both that copyright notice and this permission notice appear\n // in supporting documentation. Silicon Graphics makes no\n // representations about the suitability of this software for any\n // purpose. It is provided \"as is\" without express or implied warranty.\n //\n\nscanner/token:\n The liblangutil/{CharStream,Scanner,Token}.{h,cpp} files are derived from\n code originating from the V8 project licensed under the following terms:\n\n Copyright 2006-2012, the V8 project authors. All rights reserved.\n Redistribution and use in source and binary forms, with or without\n modification, are permitted provided that the following conditions are\n met:\n\n * Redistributions of source code must retain the above copyright\n notice, this list of conditions and the following disclaimer.\n * Redistributions in binary form must reproduce the above\n copyright notice, this list of conditions and the following\n disclaimer in the documentation and/or other materials provided\n with the distribution.\n * Neither the name of Google Inc. nor the names of its\n contributors may be used to endorse or promote products derived\n from this software without specific prior written permission.\n\n THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\n LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\n A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\n OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\n SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\n LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\n DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\n THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\n OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\nevmc:\n The code in test/evmc is licensed under the Apache License version 2:\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n\nmini-lz4:\n The file scripts/ci/mini-lz4.js is derived from the emscripten adaptation of\n node-lz4 and licensed under the following terms:\n\n Copyright (c) 2012 Pierre Curto\n\n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n\n The above copyright notice and this permission notice shall be included in\n all copies or substantial portions of the Software.\n\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\n THE SOFTWARE.\n\nbase64:\n The file scripts/ci/base64DecToArr.js is derived from a code example\n in the MDN Web Docs, which permits use under CC0 terms:\n\n Any copyright is dedicated to the Public Domain. http://creativecommons.org/publicdomain/zero/1.0/\n\nZ3:\n The Z3 library is licensed under the following terms:\n\n Copyright (c) Microsoft Corporation\n All rights reserved.\n MIT License\n\n Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\n The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\n THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n\nAll other code is licensed under GPL version 3:\n\n)\"};\n\nstatic char const licenseText[] = {\n\t@LICENSE_TEXT@, 0\n};\n" }, { "path": "cmake/toolchains/default.cmake", "content": "" }, { "path": "cmake/toolchains/libfuzzer.cmake", "content": "# Inherit default options\ninclude(\"${CMAKE_CURRENT_LIST_DIR}/default.cmake\")\n# Build fuzzing binaries\nset(OSSFUZZ ON CACHE BOOL \"Enable fuzzer build\" FORCE)\n# Use libfuzzer as the fuzzing back-end\nset(LIB_FUZZING_ENGINE \"-fsanitize=fuzzer\" CACHE STRING \"Use libfuzzer back-end\" FORCE)\n# clang/libfuzzer specific flags for UBSan instrumentation\n# uses the more memory-efficient gold, which allows us to stay with the \"large\" resource class without OOM errors\nset(CMAKE_CXX_FLAGS \"-O1 -fno-omit-frame-pointer -gline-tables-only -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION -I /usr/local/include/c++/v1 -fsanitize=undefined -fsanitize=fuzzer-no-link -fuse-ld=gold -stdlib=libc++\" CACHE STRING \"Custom compilation flags\" FORCE)\n# Link statically against boost libraries\nset(BOOST_FOUND ON CACHE BOOL \"\" FORCE)\nset(Boost_USE_STATIC_LIBS ON CACHE BOOL \"Link against static Boost libraries\" FORCE)\nset(Boost_USE_STATIC_RUNTIME ON CACHE BOOL \"Link against static Boost runtime library\" FORCE)\n" }, { "path": "cmake/toolchains/ossfuzz.cmake", "content": "# Inherit default options\ninclude(\"${CMAKE_CURRENT_LIST_DIR}/default.cmake\")\n# Disable Z3.\nset(USE_Z3 OFF CACHE BOOL \"Disable Z3\" FORCE)\n# Enable fuzzers\nset(OSSFUZZ ON CACHE BOOL \"Enable fuzzer build\" FORCE)\nset(LIB_FUZZING_ENGINE $ENV{LIB_FUZZING_ENGINE} CACHE STRING \"Use fuzzer back-end defined by environment variable\" FORCE)\n# Link statically against boost libraries\nset(BOOST_FOUND ON CACHE BOOL \"\" FORCE)\nset(Boost_USE_STATIC_LIBS ON CACHE BOOL \"Link against static Boost libraries\" FORCE)\nset(Boost_USE_STATIC_RUNTIME ON CACHE BOOL \"Link against static Boost runtime library\" FORCE)\n" }, { "path": "docs/050-breaking-changes.rst", "content": "********************************\nSolidity v0.5.0 Breaking Changes\n********************************\n\nThis section highlights the main breaking changes introduced in Solidity\nversion 0.5.0, along with the reasoning behind the changes and how to update\naffected code.\nFor the full list check\n`the release changelog `_.\n\n.. note::\n Contracts compiled with Solidity v0.5.0 can still interface with contracts\n and even libraries compiled with older versions without recompiling or\n redeploying them. Changing the interfaces to include data locations and\n visibility and mutability specifiers suffices. See the\n :ref:`Interoperability With Older Contracts ` section below.\n\nSemantic Only Changes\n=====================\n\nThis section lists the changes that are semantic-only, thus potentially\nhiding new and different behavior in existing code.\n\n* Signed right shift now uses proper arithmetic shift, i.e. rounding towards\n negative infinity, instead of rounding towards zero. Signed and unsigned\n shift will have dedicated opcodes in Constantinople, and are emulated by\n Solidity for the moment.\n\n* The ``continue`` statement in a ``do...while`` loop now jumps to the\n condition, which is the common behavior in such cases. It used to jump to the\n loop body. Thus, if the condition is false, the loop terminates.\n\n* The functions ``.call()``, ``.delegatecall()`` and ``.staticcall()`` do not\n pad anymore when given a single ``bytes`` parameter.\n\n* Pure and view functions are now called using the opcode ``STATICCALL``\n instead of ``CALL`` if the EVM version is Byzantium or later. This\n disallows state changes on the EVM level.\n\n* The ABI encoder now properly pads byte arrays and strings from calldata\n (``msg.data`` and external function parameters) when used in external\n function calls and in ``abi.encode``. For unpadded encoding, use\n ``abi.encodePacked``.\n\n* The ABI decoder reverts in the beginning of functions and in\n ``abi.decode()`` if passed calldata is too short or points out of bounds.\n Note that dirty higher order bits are still simply ignored.\n\n* Forward all available gas with external function calls starting from\n Tangerine Whistle.\n\nSemantic and Syntactic Changes\n==============================\n\nThis section highlights changes that affect syntax and semantics.\n\n* The functions ``.call()``, ``.delegatecall()``, ``staticcall()``,\n ``keccak256()``, ``sha256()`` and ``ripemd160()`` now accept only a single\n ``bytes`` argument. Moreover, the argument is not padded. This was changed to\n make more explicit and clear how the arguments are concatenated. Change every\n ``.call()`` (and family) to a ``.call(\"\")`` and every ``.call(signature, a,\n b, c)`` to use ``.call(abi.encodeWithSignature(signature, a, b, c))`` (the\n last one only works for value types). Change every ``keccak256(a, b, c)`` to\n ``keccak256(abi.encodePacked(a, b, c))``. Even though it is not a breaking\n change, it is suggested that developers change\n ``x.call(bytes4(keccak256(\"f(uint256)\")), a, b)`` to\n ``x.call(abi.encodeWithSignature(\"f(uint256)\", a, b))``.\n\n* Functions ``.call()``, ``.delegatecall()`` and ``.staticcall()`` now return\n ``(bool, bytes memory)`` to provide access to the return data. Change\n ``bool success = otherContract.call(\"f\")`` to ``(bool success, bytes memory\n data) = otherContract.call(\"f\")``.\n\n* Solidity now implements C99-style scoping rules for function local\n variables, that is, variables can only be used after they have been\n declared and only in the same or nested scopes. Variables declared in the\n initialization block of a ``for`` loop are valid at any point inside the\n loop.\n\nExplicitness Requirements\n=========================\n\nThis section lists changes where the code now needs to be more explicit.\nFor most of the topics the compiler will provide suggestions.\n\n* Explicit function visibility is now mandatory. Add ``public`` to every\n function and constructor, and ``external`` to every fallback or interface\n function that does not specify its visibility already.\n\n* Explicit data location for all variables of struct, array or mapping types is\n now mandatory. This is also applied to function parameters and return\n variables. For example, change ``uint[] x = z`` to ``uint[] storage x =\n z``, and ``function f(uint[][] x)`` to ``function f(uint[][] memory x)``\n where ``memory`` is the data location and might be replaced by ``storage`` or\n ``calldata`` accordingly. Note that ``external`` functions require\n parameters with a data location of ``calldata``.\n\n* Contract types do not include ``address`` members anymore in\n order to separate the namespaces. Therefore, it is now necessary to\n explicitly convert values of contract type to addresses before using an\n ``address`` member. Example: if ``c`` is a contract, change\n ``c.transfer(...)`` to ``address(c).transfer(...)``,\n and ``c.balance`` to ``address(c).balance``.\n\n* Explicit conversions between unrelated contract types are now disallowed. You can only\n convert from a contract type to one of its base or ancestor types. If you are sure that\n a contract is compatible with the contract type you want to convert to, although it does not\n inherit from it, you can work around this by converting to ``address`` first.\n Example: if ``A`` and ``B`` are contract types, ``B`` does not inherit from ``A`` and\n ``b`` is a contract of type ``B``, you can still convert ``b`` to type ``A`` using ``A(address(b))``.\n Note that you still need to watch out for matching payable fallback functions, as explained below.\n\n* The ``address`` type was split into ``address`` and ``address payable``,\n where only ``address payable`` provides the ``transfer`` function. An\n ``address payable`` can be directly converted to an ``address``, but the\n other way around is not allowed. Converting ``address`` to ``address\n payable`` is possible via conversion through ``uint160``. If ``c`` is a\n contract, ``address(c)`` results in ``address payable`` only if ``c`` has a\n payable fallback function. If you use the :ref:`withdraw pattern`,\n you most likely do not have to change your code because ``transfer``\n is only used on ``msg.sender`` instead of stored addresses and ``msg.sender``\n is an ``address payable``.\n\n* Conversions between ``bytesX`` and ``uintY`` of different size are now\n disallowed due to ``bytesX`` padding on the right and ``uintY`` padding on\n the left which may cause unexpected conversion results. The size must now be\n adjusted within the type before the conversion. For example, you can convert\n a ``bytes4`` (4 bytes) to a ``uint64`` (8 bytes) by first converting the\n ``bytes4`` variable to ``bytes8`` and then to ``uint64``. You get the\n opposite padding when converting through ``uint32``. Before v0.5.0 any\n conversion between ``bytesX`` and ``uintY`` would go through ``uint8X``. For\n example ``uint8(bytes3(0x291807))`` would be converted to ``uint8(uint24(bytes3(0x291807)))``\n (the result is ``0x07``).\n\n* Using ``msg.value`` in non-payable functions (or introducing it via a\n modifier) is disallowed as a security feature. Turn the function into\n ``payable`` or create a new internal function for the program logic that\n uses ``msg.value``.\n\n* For clarity reasons, the command-line interface now requires ``-`` if the\n standard input is used as source.\n\nDeprecated Elements\n===================\n\nThis section lists changes that deprecate prior features or syntax. Note that\nmany of these changes were already enabled in the experimental mode\n``v0.5.0``.\n\nCommand-line and JSON Interfaces\n--------------------------------\n\n* The command-line option ``--formal`` (used to generate Why3 output for\n further formal verification) was deprecated and is now removed. A new\n formal verification module, the SMTChecker, is enabled via ``pragma\n experimental SMTChecker;``.\n\n* The command-line option ``--julia`` was renamed to ``--yul`` due to the\n renaming of the intermediate language ``Julia`` to ``Yul``.\n\n* The ``--clone-bin`` and ``--combined-json clone-bin`` command-line options\n were removed.\n\n* Remappings with empty prefix are disallowed.\n\n* The JSON AST fields ``constant`` and ``payable`` were removed. The\n information is now present in the ``stateMutability`` field.\n\n* The JSON AST field ``isConstructor`` of the ``FunctionDefinition``\n node was replaced by a field called ``kind`` which can have the\n value ``\"constructor\"``, ``\"fallback\"`` or ``\"function\"``.\n\n* In unlinked binary hex files, library address placeholders are now\n the first 36 hex characters of the keccak256 hash of the fully qualified\n library name, surrounded by ``$...$``. Previously,\n just the fully qualified library name was used.\n This reduces the chances of collisions, especially when long paths are used.\n Binary files now also contain a list of mappings from these placeholders\n to the fully qualified names.\n\nConstructors\n------------\n\n* Constructors must now be defined using the ``constructor`` keyword.\n\n* Calling base constructors without parentheses is now disallowed.\n\n* Specifying base constructor arguments multiple times in the same inheritance\n hierarchy is now disallowed.\n\n* Calling a constructor with arguments but with wrong argument count is now\n disallowed. If you only want to specify an inheritance relation without\n giving arguments, do not provide parentheses at all.\n\nFunctions\n---------\n\n* Function ``callcode`` is now disallowed (in favor of ``delegatecall``). It\n is still possible to use it via inline assembly.\n\n* ``suicide`` is now disallowed (in favor of ``selfdestruct``).\n\n* ``sha3`` is now disallowed (in favor of ``keccak256``).\n\n* ``throw`` is now disallowed (in favor of ``revert``, ``require`` and\n ``assert``).\n\nConversions\n-----------\n\n* Explicit and implicit conversions from decimal literals to ``bytesXX`` types\n is now disallowed.\n\n* Explicit and implicit conversions from hex literals to ``bytesXX`` types\n of different size is now disallowed.\n\nLiterals and Suffixes\n---------------------\n\n* The unit denomination ``years`` is now disallowed due to complications and\n confusions about leap years.\n\n* Trailing dots that are not followed by a number are now disallowed.\n\n* Combining hex numbers with unit denominations (e.g. ``0x1e wei``) is now\n disallowed.\n\n* The prefix ``0X`` for hex numbers is disallowed, only ``0x`` is possible.\n\nVariables\n---------\n\n* Declaring empty structs is now disallowed for clarity.\n\n* The ``var`` keyword is now disallowed to favor explicitness.\n\n* Assignments between tuples with different number of components is now\n disallowed.\n\n* Values for constants that are not compile-time constants are disallowed.\n\n* Multi-variable declarations with mismatching number of values are now\n disallowed.\n\n* Uninitialized storage variables are now disallowed.\n\n* Empty tuple components are now disallowed.\n\n* Detecting cyclic dependencies in variables and structs is limited in\n recursion to 256.\n\n* Fixed-size arrays with a length of zero are now disallowed.\n\nSyntax\n------\n\n* Using ``constant`` as function state mutability modifier is now disallowed.\n\n* Boolean expressions cannot use arithmetic operations.\n\n* The unary ``+`` operator is now disallowed.\n\n* Literals cannot anymore be used with ``abi.encodePacked`` without prior\n conversion to an explicit type.\n\n* Empty return statements for functions with one or more return values are now\n disallowed.\n\n* The \"loose assembly\" syntax is now disallowed entirely, that is, jump labels,\n jumps and non-functional instructions cannot be used anymore. Use the new\n ``while``, ``switch`` and ``if`` constructs instead.\n\n* Functions without implementation cannot use modifiers anymore.\n\n* Function types with named return values are now disallowed.\n\n* Single statement variable declarations inside if/while/for bodies that are\n not blocks are now disallowed.\n\n* New keywords: ``calldata`` and ``constructor``.\n\n* New reserved keywords: ``alias``, ``apply``, ``auto``, ``copyof``,\n ``define``, ``immutable``, ``implements``, ``macro``, ``mutable``,\n ``override``, ``partial``, ``promise``, ``reference``, ``sealed``,\n ``sizeof``, ``supports``, ``typedef`` and ``unchecked``.\n\n.. _interoperability:\n\nInteroperability With Older Contracts\n=====================================\n\nIt is still possible to interface with contracts written for Solidity versions prior to\nv0.5.0 (or the other way around) by defining interfaces for them.\nConsider you have the following pre-0.5.0 contract already deployed:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.4.25;\n // This will report a warning until version 0.4.25 of the compiler\n // This will not compile after 0.5.0\n contract OldContract {\n function someOldFunction(uint8 a) {\n //...\n }\n function anotherOldFunction() constant returns (bool) {\n //...\n }\n // ...\n }\n\nThis will no longer compile with Solidity v0.5.0. However, you can define a compatible interface for it:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n interface OldContract {\n function someOldFunction(uint8 a) external;\n function anotherOldFunction() external returns (bool);\n }\n\nNote that we did not declare ``anotherOldFunction`` to be ``view``, despite it being declared ``constant`` in the original\ncontract. This is due to the fact that starting with Solidity v0.5.0 ``staticcall`` is used to call ``view`` functions.\nPrior to v0.5.0 the ``constant`` keyword was not enforced, so calling a function declared ``constant`` with ``staticcall``\nmay still revert, since the ``constant`` function may still attempt to modify storage. Consequently, when defining an\ninterface for older contracts, you should only use ``view`` in place of ``constant`` in case you are absolutely sure that\nthe function will work with ``staticcall``.\n\nGiven the interface defined above, you can now easily use the already deployed pre-0.5.0 contract:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n\n interface OldContract {\n function someOldFunction(uint8 a) external;\n function anotherOldFunction() external returns (bool);\n }\n\n contract NewContract {\n function doSomething(OldContract a) public returns (bool) {\n a.someOldFunction(0x42);\n return a.anotherOldFunction();\n }\n }\n\nSimilarly, pre-0.5.0 libraries can be used by defining the functions of the library without implementation and\nsupplying the address of the pre-0.5.0 library during linking (see :ref:`commandline-compiler` for how to use the\ncommandline compiler for linking):\n\n.. code-block:: solidity\n\n // This will not compile after 0.6.0\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.5.0;\n\n library OldLibrary {\n function someFunction(uint8 a) public returns(bool);\n }\n\n contract NewContract {\n function f(uint8 a) public returns (bool) {\n return OldLibrary.someFunction(a);\n }\n }\n\n\nExample\n=======\n\nThe following example shows a contract and its updated version for Solidity\nv0.5.0 with some of the changes listed in this section.\n\nOld version:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.4.25;\n // This will not compile after 0.5.0\n\n contract OtherContract {\n uint x;\n function f(uint y) external {\n x = y;\n }\n function() payable external {}\n }\n\n contract Old {\n OtherContract other;\n uint myNumber;\n\n // Function mutability not provided, not an error.\n function someInteger() internal returns (uint) { return 2; }\n\n // Function visibility not provided, not an error.\n // Function mutability not provided, not an error.\n function f(uint x) returns (bytes) {\n // Var is fine in this version.\n var z = someInteger();\n x += z;\n // Throw is fine in this version.\n if (x > 100)\n throw;\n bytes memory b = new bytes(x);\n y = -3 >> 1;\n // y == -1 (wrong, should be -2)\n do {\n x += 1;\n if (x > 10) continue;\n // 'Continue' causes an infinite loop.\n } while (x < 11);\n // Call returns only a Bool.\n bool success = address(other).call(\"f\");\n if (!success)\n revert();\n else {\n // Local variables could be declared after their use.\n int y;\n }\n return b;\n }\n\n // No need for an explicit data location for 'arr'\n function g(uint[] arr, bytes8 x, OtherContract otherContract) public {\n otherContract.transfer(1 ether);\n\n // Since uint32 (4 bytes) is smaller than bytes8 (8 bytes),\n // the first 4 bytes of x will be lost. This might lead to\n // unexpected behavior since bytesX are right padded.\n uint32 y = uint32(x);\n myNumber += y + msg.value;\n }\n }\n\nNew version:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.5.0;\n // This will not compile after 0.6.0\n\n contract OtherContract {\n uint x;\n function f(uint y) external {\n x = y;\n }\n function() payable external {}\n }\n\n contract New {\n OtherContract other;\n uint myNumber;\n\n // Function mutability must be specified.\n function someInteger() internal pure returns (uint) { return 2; }\n\n // Function visibility must be specified.\n // Function mutability must be specified.\n function f(uint x) public returns (bytes memory) {\n // The type must now be explicitly given.\n uint z = someInteger();\n x += z;\n // Throw is now disallowed.\n require(x <= 100);\n int y = -3 >> 1;\n require(y == -2);\n do {\n x += 1;\n if (x > 10) continue;\n // 'Continue' jumps to the condition below.\n } while (x < 11);\n\n // Call returns (bool, bytes).\n // Data location must be specified.\n (bool success, bytes memory data) = address(other).call(\"f\");\n if (!success)\n revert();\n return data;\n }\n\n using AddressMakePayable for address;\n // Data location for 'arr' must be specified\n function g(uint[] memory /* arr */, bytes8 x, OtherContract otherContract, address unknownContract) public payable {\n // 'otherContract.transfer' is not provided.\n // Since the code of 'OtherContract' is known and has the fallback\n // function, address(otherContract) has type 'address payable'.\n address(otherContract).transfer(1 ether);\n\n // 'unknownContract.transfer' is not provided.\n // 'address(unknownContract).transfer' is not provided\n // since 'address(unknownContract)' is not 'address payable'.\n // If the function takes an 'address' which you want to send\n // funds to, you can convert it to 'address payable' via 'uint160'.\n // Note: This is not recommended and the explicit type\n // 'address payable' should be used whenever possible.\n // To increase clarity, we suggest the use of a library for\n // the conversion (provided after the contract in this example).\n address payable addr = unknownContract.makePayable();\n require(addr.send(1 ether));\n\n // Since uint32 (4 bytes) is smaller than bytes8 (8 bytes),\n // the conversion is not allowed.\n // We need to convert to a common size first:\n bytes4 x4 = bytes4(x); // Padding happens on the right\n uint32 y = uint32(x4); // Conversion is consistent\n // 'msg.value' cannot be used in a 'non-payable' function.\n // We need to make the function payable\n myNumber += y + msg.value;\n }\n }\n\n // We can define a library for explicitly converting ``address``\n // to ``address payable`` as a workaround.\n library AddressMakePayable {\n function makePayable(address x) internal pure returns (address payable) {\n return address(uint160(x));\n }\n }\n" }, { "path": "docs/060-breaking-changes.rst", "content": "********************************\nSolidity v0.6.0 Breaking Changes\n********************************\n\nThis section highlights the main breaking changes introduced in Solidity\nversion 0.6.0, along with the reasoning behind the changes and how to update\naffected code.\nFor the full list check\n`the release changelog `_.\n\n\nChanges the Compiler Might not Warn About\n=========================================\n\nThis section lists changes where the behavior of your code might\nchange without the compiler telling you about it.\n\n* The resulting type of an exponentiation is the type of the base. It used to be the smallest type\n that can hold both the type of the base and the type of the exponent, as with symmetric\n operations. Additionally, signed types are allowed for the base of the exponentiation.\n\n\nExplicitness Requirements\n=========================\n\nThis section lists changes where the code now needs to be more explicit,\nbut the semantics do not change.\nFor most of the topics the compiler will provide suggestions.\n\n* Functions can now only be overridden when they are either marked with the\n ``virtual`` keyword or defined in an interface. Functions without\n implementation outside an interface have to be marked ``virtual``.\n When overriding a function or modifier, the new keyword ``override``\n must be used. When overriding a function or modifier defined in multiple\n parallel bases, all bases must be listed in parentheses after the keyword\n like so: ``override(Base1, Base2)``.\n\n* Member-access to ``length`` of arrays is now always read-only, even for storage arrays. It is no\n longer possible to resize storage arrays by assigning a new value to their length. Use ``push()``,\n ``push(value)`` or ``pop()`` instead, or assign a full array, which will of course overwrite the existing content.\n The reason behind this is to prevent storage collisions of gigantic\n storage arrays.\n\n* The new keyword ``abstract`` can be used to mark contracts as abstract. It has to be used\n if a contract does not implement all its functions. Abstract contracts cannot be created using the ``new`` operator,\n and it is not possible to generate bytecode for them during compilation.\n\n* Libraries have to implement all their functions, not only the internal ones.\n\n* The names of variables declared in inline assembly may no longer end in ``_slot`` or ``_offset``.\n\n* Variable declarations in inline assembly may no longer shadow any declaration outside the inline assembly block.\n If the name contains a dot, its prefix up to the dot may not conflict with any declaration outside the inline\n assembly block.\n\n* 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()``.\n\n* State variable shadowing is now disallowed. A derived contract can only\n declare a state variable ``x``, if there is no visible state variable with\n the same name in any of its bases.\n\n\nSemantic and Syntactic Changes\n==============================\n\nThis section lists changes where you have to modify your code\nand it does something else afterwards.\n\n* Conversions from external function types to ``address`` are now disallowed. Instead external\n function types have a member called ``address``, similar to the existing ``selector`` member.\n\n* The function ``push(value)`` for dynamic storage arrays does not return the new length anymore (it returns nothing).\n\n* The unnamed function commonly referred to as \"fallback function\" was split up into a new\n fallback function that is defined using the ``fallback`` keyword and a receive ether function\n defined using the ``receive`` keyword.\n\n * If present, the receive ether function is called whenever the call data is empty (whether\n or not ether is received). This function is implicitly ``payable``.\n\n * The new fallback function is called when no other function matches (if the receive ether\n function does not exist then this includes calls with empty call data).\n You can make this function ``payable`` or not. If it is not ``payable`` then transactions\n not matching any other function which send value will revert. You should only need to\n implement the new fallback function if you are following an upgrade or proxy pattern.\n\n\nNew Features\n============\n\nThis section lists things that were not possible prior to Solidity 0.6.0\nor were more difficult to achieve.\n\n* The :ref:`try/catch statement ` allows you to react on failed external calls.\n* ``struct`` and ``enum`` types can be declared at file level.\n* Array slices can be used for calldata arrays, for example ``abi.decode(msg.data[4:], (uint, uint))``\n is a low-level way to decode the function call payload.\n* Natspec supports multiple return parameters in developer documentation, enforcing the same naming check as ``@param``.\n* Yul and Inline Assembly have a new statement called ``leave`` that exits the current function.\n* Conversions from ``address`` to ``address payable`` are now possible via ``payable(x)``, where\n ``x`` must be of type ``address``.\n\n\nInterface Changes\n=================\n\nThis section lists changes that are unrelated to the language itself, but that have an effect on the interfaces of\nthe compiler. These may change the way how you use the compiler on the command-line, how you use its programmable\ninterface, or how you analyze the output produced by it.\n\nNew Error Reporter\n~~~~~~~~~~~~~~~~~~\n\nA new error reporter was introduced, which aims at producing more accessible error messages on the command-line.\nIt is enabled by default, but passing ``--old-reporter`` falls back to the deprecated old error reporter.\n\nMetadata Hash Options\n~~~~~~~~~~~~~~~~~~~~~\n\nThe compiler now appends the `IPFS `_ hash of the metadata file to the end of the bytecode by default\n(for details, see documentation on :doc:`contract metadata `). Before 0.6.0, the compiler appended the\n`Swarm `_ hash by default, and in order to still support this behavior,\nthe new command-line option ``--metadata-hash`` was introduced. It allows you to select the hash to be produced and\nappended, by passing either ``ipfs`` or ``swarm`` as value to the ``--metadata-hash`` command-line option.\nPassing the value ``none`` completely removes the hash.\n\nThese changes can also be used via the :ref:`Standard JSON Interface` and effect the metadata JSON generated by the compiler.\n\nThe recommended way to read the metadata is to read the last two bytes to determine the length of the CBOR encoding\nand perform a proper decoding on that data block as explained in the :ref:`metadata section`.\n\nYul Optimizer\n~~~~~~~~~~~~~\n\nTogether with the legacy bytecode optimizer, the :doc:`Yul ` optimizer is now enabled by default when you call the compiler\nwith ``--optimize``. It can be disabled by calling the compiler with ``--no-optimize-yul``.\nThis mostly affects code that uses ABI coder v2.\n\nC API Changes\n~~~~~~~~~~~~~\n\nThe client code that uses the C API of ``libsolc`` is now in control of the memory used by the compiler. To make\nthis change consistent, ``solidity_free`` was renamed to ``solidity_reset``, the functions ``solidity_alloc`` and\n``solidity_free`` were added and ``solidity_compile`` now returns a string that must be explicitly freed via\n``solidity_free()``.\n\n\nHow to update your code\n=======================\n\nThis section gives detailed instructions on how to update prior code for every breaking change.\n\n* Change ``address(f)`` to ``f.address`` for ``f`` being of external function type.\n\n* Replace ``function () external [payable] { ... }`` by either ``receive() external payable { ... }``,\n ``fallback() external [payable] { ... }`` or both. Prefer\n using a ``receive`` function only, whenever possible.\n\n* Change ``uint length = array.push(value)`` to ``array.push(value);``. The new length can be\n accessed via ``array.length``.\n\n* Change ``array.length++`` to ``array.push()`` to increase, and use ``pop()`` to decrease\n the length of a storage array.\n\n* For every named return parameter in a function's ``@dev`` documentation define a ``@return``\n entry which contains the parameter's name as the first word. E.g. if you have function ``f()`` defined\n like ``function f() public returns (uint value)`` and a ``@dev`` annotating it, document its return\n parameters like so: ``@return value The return value.``. You can mix named and un-named return parameters\n documentation so long as the notices are in the order they appear in the tuple return type.\n\n* Choose unique identifiers for variable declarations in inline assembly that do not conflict\n with declarations outside the inline assembly block.\n\n* Add ``virtual`` to every non-interface function you intend to override. Add ``virtual``\n to all functions without implementation outside interfaces. For single inheritance, add\n ``override`` to every overriding function. For multiple inheritance, add ``override(A, B, ..)``,\n where you list all contracts that define the overridden function in the parentheses. When\n multiple bases define the same function, the inheriting contract must override all conflicting functions.\n\n* In inline assembly, add ``()`` to all opcodes that do not otherwise accept an argument.\n For example, change ``pc`` to ``pc()``, and ``gas`` to ``gas()``.\n" }, { "path": "docs/070-breaking-changes.rst", "content": "********************************\nSolidity v0.7.0 Breaking Changes\n********************************\n\nThis section highlights the main breaking changes introduced in Solidity\nversion 0.7.0, along with the reasoning behind the changes and how to update\naffected code.\nFor the full list check\n`the release changelog `_.\n\n\nSilent Changes of the Semantics\n===============================\n\n* Exponentiation and shifts of literals by non-literals (e.g. ``1 << x`` or ``2 ** x``)\n will always use either the type ``uint256`` (for non-negative literals) or\n ``int256`` (for negative literals) to perform the operation.\n Previously, the operation was performed in the type of the shift amount / the\n exponent which can be misleading.\n\n\nChanges to the Syntax\n=====================\n\n* In external function and contract creation calls, Ether and gas is now specified using a new syntax:\n ``x.f{gas: 10000, value: 2 ether}(arg1, arg2)``.\n The old syntax -- ``x.f.gas(10000).value(2 ether)(arg1, arg2)`` -- will cause an error.\n\n* The global variable ``now`` is deprecated, ``block.timestamp`` should be used instead.\n The single identifier ``now`` is too generic for a global variable and could give the impression\n that it changes during transaction processing, whereas ``block.timestamp`` correctly\n reflects the fact that it is just a property of the block.\n\n* NatSpec comments on variables are only allowed for public state variables and not\n for local or internal variables.\n\n* The token ``gwei`` is a keyword now (used to specify, e.g. ``2 gwei`` as a number)\n and cannot be used as an identifier.\n\n* String literals now can only contain printable ASCII characters and this also includes a variety of\n escape sequences, such as hexadecimal (``\\xff``) and unicode escapes (``\\u20ac``).\n\n* Unicode string literals are supported now to accommodate valid UTF-8 sequences. They are identified\n with the ``unicode`` prefix: ``unicode\"Hello 😃\"``.\n\n* State Mutability: The state mutability of functions can now be restricted during inheritance:\n Functions with default state mutability can be overridden by ``pure`` and ``view`` functions\n while ``view`` functions can be overridden by ``pure`` functions.\n At the same time, public state variables are considered ``view`` and even ``pure``\n if they are constants.\n\n\n\nInline Assembly\n---------------\n\n* Disallow ``.`` in user-defined function and variable names in inline assembly.\n It is still valid if you use Solidity in Yul-only mode.\n\n* Slot and offset of storage pointer variable ``x`` are accessed via ``x.slot``\n and ``x.offset`` instead of ``x_slot`` and ``x_offset``.\n\nRemoval of Unused or Unsafe Features\n====================================\n\nMappings outside Storage\n------------------------\n\n* If a struct or array contains a mapping, it can only be used in storage.\n Previously, mapping members were silently skipped in memory, which\n is confusing and error-prone.\n\n* Assignments to structs or arrays in storage does not work if they contain\n mappings.\n Previously, mappings were silently skipped during the copy operation, which\n is misleading and error-prone.\n\nFunctions and Events\n--------------------\n\n* Visibility (``public`` / ``internal``) is not needed for constructors anymore:\n To prevent a contract from being created, it can be marked ``abstract``.\n This makes the visibility concept for constructors obsolete.\n\n* Type Checker: Disallow ``virtual`` for library functions:\n Since libraries cannot be inherited from, library functions should not be virtual.\n\n* Multiple events with the same name and parameter types in the same\n inheritance hierarchy are disallowed.\n\n* ``using A for B`` only affects the contract it is mentioned in.\n Previously, the effect was inherited. Now, you have to repeat the ``using``\n statement in all derived contracts that make use of the feature.\n\nExpressions\n-----------\n\n* Shifts by signed types are disallowed.\n Previously, shifts by negative amounts were allowed, but reverted at runtime.\n\n* The ``finney`` and ``szabo`` denominations are removed.\n They are rarely used and do not make the actual amount readily visible. Instead, explicit\n values like ``1e20`` or the very common ``gwei`` can be used.\n\nDeclarations\n------------\n\n* The keyword ``var`` cannot be used anymore.\n Previously, this keyword would parse but result in a type error and\n a suggestion about which type to use. Now, it results in a parser error.\n\nInterface Changes\n=================\n\n* JSON AST: Mark hex string literals with ``kind: \"hexString\"``.\n* JSON AST: Members with value ``null`` are removed from JSON output.\n* NatSpec: Constructors and functions have consistent userdoc output.\n\n\nHow to update your code\n=======================\n\nThis section gives detailed instructions on how to update prior code for every breaking change.\n\n* Change ``x.f.value(...)()`` to ``x.f{value: ...}()``. Similarly ``(new C).value(...)()`` to\n ``new C{value: ...}()`` and ``x.f.gas(...).value(...)()`` to ``x.f{gas: ..., value: ...}()``.\n* Change ``now`` to ``block.timestamp``.\n* Change types of right operand in shift operators to unsigned types. For example change ``x >> (256 - y)`` to\n ``x >> uint(256 - y)``.\n* Repeat the ``using A for B`` statements in all derived contracts if needed.\n* Remove the ``public`` keyword from every constructor.\n* Remove the ``internal`` keyword from every constructor and add ``abstract`` to the contract (if not already present).\n* Change ``_slot`` and ``_offset`` suffixes in inline assembly to ``.slot`` and ``.offset``, respectively.\n" }, { "path": "docs/080-breaking-changes.rst", "content": "********************************\nSolidity v0.8.0 Breaking Changes\n********************************\n\nThis section highlights the main breaking changes introduced in Solidity\nversion 0.8.0.\nFor the full list check\n`the release changelog `_.\n\nSilent Changes of the Semantics\n===============================\n\nThis section lists changes where existing code changes its behavior without\nthe compiler notifying you about it.\n\n* Arithmetic operations revert on underflow and overflow. You can use ``unchecked { ... }`` to use\n the previous wrapping behavior.\n\n Checks for overflow are very common, so we made them the default to increase readability of code,\n even if it comes at a slight increase of gas costs.\n\n* ABI coder v2 is activated by default.\n\n You can choose to use the old behavior using ``pragma abicoder v1;``.\n The pragma ``pragma experimental ABIEncoderV2;`` is still valid, but it is deprecated and has no effect.\n If you want to be explicit, please use ``pragma abicoder v2;`` instead.\n\n Note that ABI coder v2 supports more types than v1 and performs more sanity checks on the inputs.\n ABI coder v2 makes some function calls more expensive and it can also make contract calls\n revert that did not revert with ABI coder v1 when they contain data that does not conform to the\n parameter types.\n\n* Exponentiation is right associative, i.e., the expression ``a**b**c`` is parsed as ``a**(b**c)``.\n Before 0.8.0, it was parsed as ``(a**b)**c``.\n\n This is the common way to parse the exponentiation operator.\n\n* Failing assertions and other internal checks like division by zero or arithmetic overflow do\n not use the invalid opcode but instead the revert opcode.\n More specifically, they will use error data equal to a function call to ``Panic(uint256)`` with an error code specific\n to the circumstances.\n\n This will save gas on errors while it still allows static analysis tools to distinguish\n these situations from a revert on invalid input, like a failing ``require``.\n\n* If a byte array in storage is accessed whose length is encoded incorrectly, a panic is caused.\n A contract cannot get into this situation unless inline assembly is used to modify the raw representation of storage byte arrays.\n\n* If constants are used in array length expressions, previous versions of Solidity would use arbitrary precision\n in all branches of the evaluation tree. Now, if constant variables are used as intermediate expressions,\n their values will be properly rounded in the same way as when they are used in run-time expressions.\n\n* The type ``byte`` has been removed. It was an alias of ``bytes1``.\n\nNew Restrictions\n================\n\nThis section lists changes that might cause existing contracts to not compile anymore.\n\n* There are new restrictions related to explicit conversions of literals. The previous behavior in\n the following cases was likely ambiguous:\n\n 1. Explicit conversions from negative literals and literals larger than ``type(uint160).max`` to\n ``address`` are disallowed.\n 2. Explicit conversions between literals and an integer type ``T`` are only allowed if the literal\n lies between ``type(T).min`` and ``type(T).max``. In particular, replace usages of ``uint(-1)``\n with ``type(uint).max``.\n 3. Explicit conversions between literals and enums are only allowed if the literal can\n represent a value in the enum.\n 4. Explicit conversions between literals and ``address`` type (e.g. ``address(literal)``) have the\n type ``address`` instead of ``address payable``. One can get a payable address type by using an\n explicit conversion, i.e., ``payable(literal)``.\n\n* :ref:`Address literals` have the type ``address`` instead of ``address\n payable``. They can be converted to ``address payable`` by using an explicit conversion, e.g.\n ``payable(0xdCad3a6d3569DF655070DEd06cb7A1b2Ccd1D3AF)``.\n\n* There are new restrictions on explicit type conversions. The conversion is only allowed when there\n is at most one change in sign, width or type-category (``int``, ``address``, ``bytesNN``, etc.).\n To perform multiple changes, use multiple conversions.\n\n Let us use the notation ``T(S)`` to denote the explicit conversion ``T(x)``, where, ``T`` and\n ``S`` are types, and ``x`` is any arbitrary variable of type ``S``. An example of such a\n disallowed conversion would be ``uint16(int8)`` since it changes both width (8 bits to 16 bits)\n and sign (signed integer to unsigned integer). In order to do the conversion, one has to go\n through an intermediate type. In the previous example, this would be ``uint16(uint8(int8))`` or\n ``uint16(int16(int8))``. Note that the two ways to convert will produce different results e.g.,\n for ``-1``. The following are some examples of conversions that are disallowed by this rule.\n\n - ``address(uint)`` and ``uint(address)``: converting both type-category and width. Replace this by\n ``address(uint160(uint))`` and ``uint(uint160(address))`` respectively.\n - ``payable(uint160)``, ``payable(bytes20)`` and ``payable(integer-literal)``: converting both\n type-category and state-mutability. Replace this by ``payable(address(uint160))``,\n ``payable(address(bytes20))`` and ``payable(address(integer-literal))`` respectively. Note that\n ``payable(0)`` is valid and is an exception to the rule.\n - ``int80(bytes10)`` and ``bytes10(int80)``: converting both type-category and sign. Replace this by\n ``int80(uint80(bytes10))`` and ``bytes10(uint80(int80)`` respectively.\n - ``Contract(uint)``: converting both type-category and width. Replace this by\n ``Contract(address(uint160(uint)))``.\n\n These conversions were disallowed to avoid ambiguity. For example, in the expression ``uint16 x =\n uint16(int8(-1))``, the value of ``x`` would depend on whether the sign or the width conversion\n was applied first.\n\n* Function call options can only be given once, i.e. ``c.f{gas: 10000}{value: 1}()`` is invalid and has to be changed to ``c.f{gas: 10000, value: 1}()``.\n\n* The global functions ``log0``, ``log1``, ``log2``, ``log3`` and ``log4`` have been removed.\n\n These are low-level functions that were largely unused. Their behavior can be accessed from inline assembly.\n\n* ``enum`` definitions cannot contain more than 256 members.\n\n This will make it safe to assume that the underlying type in the ABI is always ``uint8``.\n\n* Declarations with the name ``this``, ``super`` and ``_`` are disallowed, with the exception of\n public functions and events. The exception is to make it possible to declare interfaces of contracts\n implemented in languages other than Solidity that do permit such function names.\n\n* Remove support for the ``\\b``, ``\\f``, and ``\\v`` escape sequences in code.\n They can still be inserted via hexadecimal escapes, e.g. ``\\x08``, ``\\x0c``, and ``\\x0b``, respectively.\n\n* The global variables ``tx.origin`` and ``msg.sender`` have the type ``address`` instead of\n ``address payable``. One can convert them into ``address payable`` by using an explicit\n conversion, i.e., ``payable(tx.origin)`` or ``payable(msg.sender)``.\n\n This change was done since the compiler cannot determine whether or not these addresses\n are payable or not, so it now requires an explicit conversion to make this requirement visible.\n\n* Explicit conversion into ``address`` type always returns a non-payable ``address`` type. In\n particular, the following explicit conversions have the type ``address`` instead of ``address\n payable``:\n\n - ``address(u)`` where ``u`` is a variable of type ``uint160``. One can convert ``u``\n into the type ``address payable`` by using two explicit conversions, i.e.,\n ``payable(address(u))``.\n - ``address(b)`` where ``b`` is a variable of type ``bytes20``. One can convert ``b``\n into the type ``address payable`` by using two explicit conversions, i.e.,\n ``payable(address(b))``.\n - ``address(c)`` where ``c`` is a contract. Previously, the return type of this\n conversion depended on whether the contract can receive Ether (either by having a receive\n function or a payable fallback function). The conversion ``payable(c)`` has the type ``address\n payable`` and is only allowed when the contract ``c`` can receive Ether. In general, one can\n always convert ``c`` into the type ``address payable`` by using the following explicit\n conversion: ``payable(address(c))``. Note that ``address(this)`` falls under the same category\n as ``address(c)`` and the same rules apply for it.\n\n* The ``chainid`` builtin in inline assembly is now considered ``view`` instead of ``pure``.\n\n* Unary negation cannot be used on unsigned integers anymore, only on signed integers.\n\nInterface Changes\n=================\n\n* The output of ``--combined-json`` has changed: JSON fields ``abi``, ``devdoc``, ``userdoc`` and\n ``storage-layout`` are sub-objects now. Before 0.8.0 they used to be serialised as strings.\n\n* The \"legacy AST\" has been removed (``--ast-json`` on the commandline interface and ``legacyAST`` for standard JSON).\n Use the \"compact AST\" (``--ast-compact-json`` resp. ``AST``) as replacement.\n\n* The old error reporter (``--old-reporter``) has been removed.\n\n\nHow to update your code\n=======================\n\n- If you rely on wrapping arithmetic, surround each operation with ``unchecked { ... }``.\n- Optional: If you use SafeMath or a similar library, change ``x.add(y)`` to ``x + y``, ``x.mul(y)`` to ``x * y`` etc.\n- Add ``pragma abicoder v1;`` if you want to stay with the old ABI coder.\n- Optionally remove ``pragma experimental ABIEncoderV2`` or ``pragma abicoder v2`` since it is redundant.\n- Change ``byte`` to ``bytes1``.\n- Add intermediate explicit type conversions if required.\n- Combine ``c.f{gas: 10000}{value: 1}()`` to ``c.f{gas: 10000, value: 1}()``.\n- Change ``msg.sender.transfer(x)`` to ``payable(msg.sender).transfer(x)`` or use a stored variable of ``address payable`` type.\n- Change ``x**y**z`` to ``(x**y)**z``.\n- Use inline assembly as a replacement for ``log0``, ..., ``log4``.\n- 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)\n" }, { "path": "docs/Makefile", "content": "# Makefile for Sphinx documentation\n#\n\n# You can set these variables from the command line.\nSPHINXOPTS =\nSPHINXBUILD = sphinx-build\nPAPER =\nBUILDDIR = _build\n\n# User-friendly check for sphinx-build\nifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)\n$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)\nendif\n\n# Internal variables.\nPAPEROPT_a4 = -D latex_paper_size=a4\nPAPEROPT_letter = -D latex_paper_size=letter\nALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .\n# the i18n builder cannot share the environment and doctrees with the others\nI18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .\n\n.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext\n\nhelp:\n\t@echo \"Please use \\`make ' where is one of\"\n\t@echo \" html to make standalone HTML files\"\n\t@echo \" dirhtml to make HTML files named index.html in directories\"\n\t@echo \" singlehtml to make a single large HTML file\"\n\t@echo \" pickle to make pickle files\"\n\t@echo \" json to make JSON files\"\n\t@echo \" htmlhelp to make HTML files and a HTML help project\"\n\t@echo \" qthelp to make HTML files and a qthelp project\"\n\t@echo \" devhelp to make HTML files and a Devhelp project\"\n\t@echo \" epub to make an epub\"\n\t@echo \" latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter\"\n\t@echo \" latexpdf to make LaTeX files and run them through pdflatex\"\n\t@echo \" text to make text files\"\n\t@echo \" man to make manual pages\"\n\t@echo \" texinfo to make Texinfo files\"\n\t@echo \" info to make Texinfo files and run them through makeinfo\"\n\t@echo \" gettext to make PO message catalogs\"\n\t@echo \" changes to make an overview of all changed/added/deprecated items\"\n\t@echo \" xml to make Docutils-native XML files\"\n\t@echo \" pseudoxml to make pseudoxml-XML files for display purposes\"\n\t@echo \" linkcheck to check all external links for integrity\"\n\t@echo \" doctest to run all doctests embedded in the documentation (if enabled)\"\n\nclean:\n\trm -rf $(BUILDDIR)/*\n\nhtml:\n\t$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html\n\t@echo\n\t@echo \"Build finished. The HTML pages are in $(BUILDDIR)/html.\"\n\ndirhtml:\n\t$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml\n\t@echo\n\t@echo \"Build finished. The HTML pages are in $(BUILDDIR)/dirhtml.\"\n\nsinglehtml:\n\t$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml\n\t@echo\n\t@echo \"Build finished. The HTML page is in $(BUILDDIR)/singlehtml.\"\n\npickle:\n\t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle\n\t@echo\n\t@echo \"Build finished; now you can process the pickle files.\"\n\njson:\n\t$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json\n\t@echo\n\t@echo \"Build finished; now you can process the JSON files.\"\n\nhtmlhelp:\n\t$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp\n\t@echo\n\t@echo \"Build finished; now you can run HTML Help Workshop with the\" \\\n\t \".hhp project file in $(BUILDDIR)/htmlhelp.\"\n\nqthelp:\n\t$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp\n\t@echo\n\t@echo \"Build finished; now you can run \"qcollectiongenerator\" with the\" \\\n\t \".qhcp project file in $(BUILDDIR)/qthelp, like this:\"\n\t@echo \"# qcollectiongenerator $(BUILDDIR)/qthelp/Solidity.qhcp\"\n\t@echo \"To view the help file:\"\n\t@echo \"# assistant -collectionFile $(BUILDDIR)/qthelp/Solidity.qhc\"\n\ndevhelp:\n\t$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp\n\t@echo\n\t@echo \"Build finished.\"\n\t@echo \"To view the help file:\"\n\t@echo \"# mkdir -p $$HOME/.local/share/devhelp/Solidity\"\n\t@echo \"# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Solidity\"\n\t@echo \"# devhelp\"\n\nepub:\n\t$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub\n\t@echo\n\t@echo \"Build finished. The epub file is in $(BUILDDIR)/epub.\"\n\nlatex:\n\t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex\n\t@echo\n\t@echo \"Build finished; the LaTeX files are in $(BUILDDIR)/latex.\"\n\t@echo \"Run \\`make' in that directory to run these through (pdf)latex\" \\\n\t \"(use \\`make latexpdf' here to do that automatically).\"\n\nlatexpdf:\n\t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex\n\t@echo \"Running LaTeX files through pdflatex...\"\n\t$(MAKE) -C $(BUILDDIR)/latex all-pdf\n\t@echo \"pdflatex finished; the PDF files are in $(BUILDDIR)/latex.\"\n\ntext:\n\t$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text\n\t@echo\n\t@echo \"Build finished. The text files are in $(BUILDDIR)/text.\"\n\nman:\n\t$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man\n\t@echo\n\t@echo \"Build finished. The manual pages are in $(BUILDDIR)/man.\"\n\ntexinfo:\n\t$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo\n\t@echo\n\t@echo \"Build finished. The Texinfo files are in $(BUILDDIR)/texinfo.\"\n\t@echo \"Run \\`make' in that directory to run these through makeinfo\" \\\n\t \"(use \\`make info' here to do that automatically).\"\n\ninfo:\n\t$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo\n\t@echo \"Running Texinfo files through makeinfo...\"\n\tmake -C $(BUILDDIR)/texinfo info\n\t@echo \"makeinfo finished; the Info files are in $(BUILDDIR)/texinfo.\"\n\ngettext:\n\t$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale\n\t@echo\n\t@echo \"Build finished. The message catalogs are in $(BUILDDIR)/locale.\"\n\nchanges:\n\t$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes\n\t@echo\n\t@echo \"The overview file is in $(BUILDDIR)/changes.\"\n\nlinkcheck:\n\t$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck\n\t@echo\n\t@echo \"Link check complete; look for any errors in the above output \" \\\n\t \"or in $(BUILDDIR)/linkcheck/output.txt.\"\n\ndoctest:\n\t$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest\n\t@echo \"Testing of doctests in the sources finished, look at the \" \\\n\t \"results in $(BUILDDIR)/doctest/output.txt.\"\n\nxml:\n\t$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml\n\t@echo\n\t@echo \"Build finished. The XML files are in $(BUILDDIR)/xml.\"\n\npseudoxml:\n\t$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml\n\t@echo\n\t@echo \"Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml.\"\n" }, { "path": "docs/README.md", "content": "# Solidity Language Docs\n\n## Local environment setup\n\n1. Install python https://www.python.org/downloads/\n1. Install sphinx (the tool used to generate the docs) https://www.sphinx-doc.org/en/master/usage/installation.html\n\nGo to `/docs` and run `./docs.sh` to install dependencies and build the project:\n\n```sh\ncd docs\n./docs.sh\n```\n\nThat will output the generated htmls under _build/\n\n## Serve environment\n\n```py\npython3 -m http.server -d _build/html --cgi 8080\n```\n\nVisit dev server at http://localhost:8080\n" }, { "path": "docs/_static/css/custom-dark.css", "content": "\n\n/* DARK MODE STYLING */\n\n/* code directives */\n\n:root[style*=dark] .method dt,\n:root[style*=dark] .class dt,\n:root[style*=dark] .data dt,\n:root[style*=dark] .attribute dt,\n:root[style*=dark] .function dt,\n:root[style*=dark] .classmethod dt,\n:root[style*=dark] .exception dt,\n:root[style*=dark] .descclassname,\n:root[style*=dark] .descname {\n background-color: #2d2d2d !important;\n}\n\n:root[style*=dark] .rst-content dl:not(.docutils) dt {\n background-color: #0008;\n border-top: solid 3px #fff2;\n border-left: solid 3px #fff2;\n}\n\n:root[style*=dark] em.property {\n color: #888888;\n}\n\n\n/* tables */\n\n:root[style*=dark] .rst-content table.docutils td {\n border: 0px;\n}\n\n:root[style*=dark] .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td {\n background-color: #0002;\n}\n\n:root[style*=dark] .rst-content pre {\n background: none;\n}\n\n/* inlined code highlights */\n\n:root[style*=dark] .xref,\n:root[style*=dark] .py-meth {\n color: #aaddff !important;\n font-weight: normal !important;\n}\n\n/* highlight color search text */\n\n:root[style*=dark] .rst-content .highlighted {\n background: #ff5722;\n box-shadow: 0 0 0 2px #f0978b;\n}\n\n/* notes, warnings, hints */\n\n:root[style*=dark] .hint .admonition-title {\n background: #2aa87c !important;\n}\n\n:root[style*=dark] .warning .admonition-title {\n background: #cc4444 !important;\n}\n\n:root[style*=dark] .admonition-title {\n background: #3a7ca8 !important;\n}\n\n:root[style*=dark] .admonition,\n:root[style*=dark] .note {\n background-color: #0008 !important;\n}\n\n\n/* table of contents */\n\n:root[style*=dark] .sidebar {\n background-color: #191919 !important;\n}\n\n:root[style*=dark] .sidebar-title {\n background-color: #2b2b2b !important;\n}\n\n:root[style*=dark] .wy-menu-vertical code.docutils.literal.notranslate {\n background: none !important;\n border: none !important;\n}\n\n\n:root[style*=dark] .toc-backref {\n color: grey !important;\n}\n\n:root[style*=dark] .highlight {\n background: #0008;\n color: #f8f8f2\n}\n\n:root[style*=dark] .highlight .c {\n color: #888\n}\n\n\n/* Comment */\n\n:root[style*=dark] .highlight .err {\n color: #960050;\n background-color: #1e0010\n}\n\n\n/* Error */\n\n:root[style*=dark] .highlight .k {\n color: #66d9ef\n}\n\n\n/* Keyword */\n\n:root[style*=dark] .highlight .l {\n color: #ae81ff\n}\n\n\n/* Literal */\n\n:root[style*=dark] .highlight .n {\n color: #f8f8f2\n}\n\n\n/* Name */\n\n:root[style*=dark] .highlight .o {\n color: #f92672\n}\n\n\n/* Operator */\n\n:root[style*=dark] .highlight .p {\n color: #f8f8f2\n}\n\n\n/* Punctuation */\n\n:root[style*=dark] .highlight .ch {\n color: #888\n}\n\n\n/* Comment.Hashbang */\n\n:root[style*=dark] .highlight .cm {\n color: #888\n}\n\n\n/* Comment.Multiline */\n\n:root[style*=dark] .highlight .cp {\n color: #888\n}\n\n\n/* Comment.Preproc */\n\n:root[style*=dark] .highlight .cpf {\n color: #888\n}\n\n\n/* Comment.PreprocFile */\n\n:root[style*=dark] .highlight .c1 {\n color: #888\n}\n\n\n/* Comment.Single */\n\n:root[style*=dark] .highlight .cs {\n color: #888\n}\n\n\n/* Comment.Special */\n\n:root[style*=dark] .highlight .gd {\n color: #f92672\n}\n\n\n/* Generic.Deleted */\n\n:root[style*=dark] .highlight .ge {\n font-style: italic\n}\n\n\n/* Generic.Emph */\n\n:root[style*=dark] .highlight .gi {\n color: #a6e22e\n}\n\n\n/* Generic.Inserted */\n\n:root[style*=dark] .highlight .gs {\n font-weight: bold\n}\n\n\n/* Generic.Strong */\n\n:root[style*=dark] .highlight .gu {\n color: #888\n}\n\n\n/* Generic.Subheading */\n\n:root[style*=dark] .highlight .kc {\n color: #66d9ef\n}\n\n\n/* Keyword.Constant */\n\n:root[style*=dark] .highlight .kd {\n color: #66d9ef\n}\n\n\n/* Keyword.Declaration */\n\n:root[style*=dark] .highlight .kn {\n color: #f92672\n}\n\n\n/* Keyword.Namespace */\n\n:root[style*=dark] .highlight .kp {\n color: #66d9ef\n}\n\n\n/* Keyword.Pseudo */\n\n:root[style*=dark] .highlight .kr {\n color: #66d9ef\n}\n\n\n/* Keyword.Reserved */\n\n:root[style*=dark] .highlight .kt {\n color: #66d9ef\n}\n\n\n/* Keyword.Type */\n\n:root[style*=dark] .highlight .ld {\n color: #e6db74\n}\n\n\n/* Literal.Date */\n\n:root[style*=dark] .highlight .m {\n color: #ae81ff\n}\n\n\n/* Literal.Number */\n\n:root[style*=dark] .highlight .s {\n color: #e6db74\n}\n\n\n/* Literal.String */\n\n:root[style*=dark] .highlight .na {\n color: #a6e22e\n}\n\n\n/* Name.Attribute */\n\n:root[style*=dark] .highlight .nb {\n color: #f8f8f2\n}\n\n\n/* Name.Builtin */\n\n:root[style*=dark] .highlight .nc {\n color: #a6e22e\n}\n\n\n/* Name.Class */\n\n:root[style*=dark] .highlight .no {\n color: #66d9ef\n}\n\n\n/* Name.Constant */\n\n:root[style*=dark] .highlight .nd {\n color: #a6e22e\n}\n\n\n/* Name.Decorator */\n\n:root[style*=dark] .highlight .ni {\n color: #f8f8f2\n}\n\n\n/* Name.Entity */\n\n:root[style*=dark] .highlight .ne {\n color: #a6e22e\n}\n\n\n/* Name.Exception */\n\n:root[style*=dark] .highlight .nf {\n color: #a6e22e\n}\n\n\n/* Name.Function */\n\n:root[style*=dark] .highlight .nl {\n color: #f8f8f2\n}\n\n\n/* Name.Label */\n\n:root[style*=dark] .highlight .nn {\n color: #f8f8f2\n}\n\n\n/* Name.Namespace */\n\n:root[style*=dark] .highlight .nx {\n color: #a6e22e\n}\n\n\n/* Name.Other */\n\n:root[style*=dark] .highlight .py {\n color: #f8f8f2\n}\n\n\n/* Name.Property */\n\n:root[style*=dark] .highlight .nt {\n color: #f92672\n}\n\n\n/* Name.Tag */\n\n:root[style*=dark] .highlight .nv {\n color: #f8f8f2\n}\n\n\n/* Name.Variable */\n\n:root[style*=dark] .highlight .ow {\n color: #f92672\n}\n\n\n/* Operator.Word */\n\n:root[style*=dark] .highlight .w {\n color: #f8f8f2\n}\n\n\n/* Text.Whitespace */\n\n:root[style*=dark] .highlight .mb {\n color: #ae81ff\n}\n\n\n/* Literal.Number.Bin */\n\n:root[style*=dark] .highlight .mf {\n color: #ae81ff\n}\n\n\n/* Literal.Number.Float */\n\n:root[style*=dark] .highlight .mh {\n color: #ae81ff\n}\n\n\n/* Literal.Number.Hex */\n\n:root[style*=dark] .highlight .mi {\n color: #ae81ff\n}\n\n\n/* Literal.Number.Integer */\n\n:root[style*=dark] .highlight .mo {\n color: #ae81ff\n}\n\n\n/* Literal.Number.Oct */\n\n:root[style*=dark] .highlight .sa {\n color: #e6db74\n}\n\n\n/* Literal.String.Affix */\n\n:root[style*=dark] .highlight .sb {\n color: #e6db74\n}\n\n\n/* Literal.String.Backtick */\n\n:root[style*=dark] .highlight .sc {\n color: #e6db74\n}\n\n\n/* Literal.String.Char */\n\n:root[style*=dark] .highlight .dl {\n color: #e6db74\n}\n\n\n/* Literal.String.Delimiter */\n\n:root[style*=dark] .highlight .sd {\n color: #e6db74\n}\n\n\n/* Literal.String.Doc */\n\n:root[style*=dark] .highlight .s2 {\n color: #e6db74\n}\n\n\n/* Literal.String.Double */\n\n:root[style*=dark] .highlight .se {\n color: #ae81ff\n}\n\n\n/* Literal.String.Escape */\n\n:root[style*=dark] .highlight .sh {\n color: #e6db74\n}\n\n\n/* Literal.String.Heredoc */\n\n:root[style*=dark] .highlight .si {\n color: #e6db74\n}\n\n\n/* Literal.String.Interpol */\n\n:root[style*=dark] .highlight .sx {\n color: #e6db74\n}\n\n\n/* Literal.String.Other */\n\n:root[style*=dark] .highlight .sr {\n color: #e6db74\n}\n\n\n/* Literal.String.Regex */\n\n:root[style*=dark] .highlight .s1 {\n color: #e6db74\n}\n\n\n/* Literal.String.Single */\n\n:root[style*=dark] .highlight .ss {\n color: #e6db74\n}\n\n\n/* Literal.String.Symbol */\n\n:root[style*=dark] .highlight .bp {\n color: #f8f8f2\n}\n\n\n/* Name.Builtin.Pseudo */\n\n:root[style*=dark] .highlight .fm {\n color: #a6e22e\n}\n\n\n/* Name.Function.Magic */\n\n:root[style*=dark] .highlight .vc {\n color: #f8f8f2\n}\n\n\n/* Name.Variable.Class */\n\n:root[style*=dark] .highlight .vg {\n color: #f8f8f2\n}\n\n\n/* Name.Variable.Global */\n\n:root[style*=dark] .highlight .vi {\n color: #f8f8f2\n}\n\n\n/* Name.Variable.Instance */\n\n:root[style*=dark] .highlight .vm {\n color: #f8f8f2\n}\n\n\n/* Name.Variable.Magic */\n\n:root[style*=dark] .highlight .il {\n color: #ae81ff\n}\n\n\n/* Grammar */\n\n:root[style*=dark] .railroad-diagram {\n fill: white;\n}\n\n:root[style*=dark] .railroad-diagram path {\n stroke: white;\n}\n\n:root[style*=dark] .railroad-diagram rect {\n stroke: white;\n}\n\n:root[style*=dark] .sig-name {\n background-color: transparent !important;\n}\n" }, { "path": "docs/_static/css/custom.css", "content": "/* ROOT DECLARATIONS */\n:root {\n /* Text */\n --color-a: #2B247C;\n --color-b: #672AC8;\n --color-c: #5554D9;\n --color-d: #9F94E8;\n --color-e: #AEC0F1;\n --color-f: #E6E3EC;\n /* Background */\n\n --white: #FAF8FF;\n --black: #110C4E;\n --menu-bg: #2B247C06;\n --shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);\n\n --navHeight: 4.5rem;\n --sideWidth: 300px;\n --maxWidth: 80rem;\n --desktopInlinePadding: 2rem;\n --mobileInlinePadding: 1rem;\n --currentVersionHeight: 45px;\n\n text-rendering: geometricPrecision;\n -webkit-font-smoothing: antialiased;\n}\n\na,\nbutton {\n border-radius: 0;\n}\n\n:root[style*=dark] {\n --color-a: #E6E3EC !important;\n --color-b: #AEC0F1 !important;\n --color-c: #9F94E8 !important;\n --color-d: #5554D9 !important;\n --color-e: #672AC8 !important;\n --color-f: #2B247C !important;\n\n --white: #110C4E !important;\n --black: #FAF8FF !important;\n --menu-bg: #E6E3EC06 !important;\n}\n\nhtml,\nbody,\n.unified-header::before,\n.wy-nav-side,\n.rst-versions,\ncode,\ndiv,\ninput[type=text],\na,\n.wy-grid-for-nav {\n transition: background 150ms ease-in-out;\n}\n\nhtml,\nbody,\n.wy-grid-for-nav {\n background-color: var(--color-f) !important;\n}\n\nbody {\n font-family: \"Overpass\", sans-serif;\n}\n\na {\n color: var(--color-c);\n}\n\na, section {\n scroll-margin-top: calc(var(--navHeight) + 2rem);\n}\n\nhr {\n margin-block: 2rem;\n border-color: var(--color-d) !important;\n}\n\n\n/* HEADER STYLES */\nh1 {\n font-family: 'Overpass', sans-serif;\n font-weight: 700;\n font-size: 44px;\n color: var(--color-a) !important;\n line-height: 1.1;\n text-wrap: balance;\n margin-top: 4rem;\n margin-bottom: 1.5rem;\n}\n\nsection:first-of-type h1:first-of-type {\n font-family: 'Overpass Mono', monospace;\n font-size: 48px;\n margin-top: 3rem;\n margin-bottom: 5rem;\n}\n\nh2 {\n font-family: 'Overpass', sans-serif;\n font-weight: 700;\n font-size: 38px;\n color: var(--color-a) !important;\n line-height: 46px;\n text-wrap: balance;\n margin-top: 4rem;\n margin-bottom: 1.5rem;\n}\n\n*:not([role=navigation])>p[role=heading]>span,\nh3 {\n font-family: 'Overpass', sans-serif;\n font-weight: 700;\n font-size: 32px;\n color: var(--color-a) !important;\n line-height: 46px;\n text-wrap: balance;\n margin-top: 4rem;\n margin-bottom: 1.5rem;\n}\n\nh4 {\n font-family: 'Overpass', sans-serif;\n font-weight: 700;\n font-size: 32px;\n color: var(--color-a) !important;\n line-height: 46px;\n text-wrap: balance;\n margin-top: 3rem;\n margin-bottom: 1.5rem;\n}\n\nh5 {\n font-family: 'Overpass', sans-serif;\n font-weight: 700;\n font-size: 18px;\n color: var(--color-a) !important;\n line-height: 1.4;\n text-wrap: balance;\n}\n\nh6 {\n font-family: 'Overpass', sans-serif;\n font-weight: 700;\n font-size: 16px;\n color: var(--color-a) !important;\n line-height: 1.4;\n text-wrap: balance;\n}\n\nspan.pre,\npre {\n /* css-3 */\n white-space: pre-wrap;\n /* Mozilla, since 1999 */\n white-space: -moz-pre-wrap;\n /* Opera 4-6 */\n white-space: -pre-wrap;\n /* Opera 7 */\n white-space: -o-pre-wrap;\n word-wrap: break-word;\n font-family: 'Overpass Mono', monospace;\n}\n\nsmall,\nsmall * {\n font-size: 12px;\n}\n\n.wy-table-responsive table td,\n.wy-table-responsive table th {\n white-space: normal;\n}\n\n.rst-content table.docutils td {\n vertical-align: top;\n}\n\n/* links */\n.rst-content .highlighted {\n background: #eac545;\n}\n\n/* code block highlights */\n.rst-content pre {\n background: #fafafa;\n}\n\n/* project version (displayed under project logo) */\n.wy-side-nav-search>div.version {\n color: var(--color-b);\n margin-top: 0;\n margin-bottom: 0.5rem;\n text-align: start;\n}\n\n/* Link to Remix IDE shown next to code snippets */\n.rst-content p.remix-link-container {\n display: block;\n text-align: right;\n margin: 0;\n line-height: 1em;\n}\n\n.rst-content .remix-link-container a.remix-link {\n font-size: 0.7em;\n padding: 0.1em 0.5em;\n background: transparent;\n color: var(--color-a) !important;\n border: 1px solid var(--color-a);\n text-decoration: none;\n}\n\n.rst-content div.highlight-solidity,\n.rst-content div.highlight-yul {\n margin-top: 0;\n}\n\n/* CUSTOMIZATION UPDATES */\n\n.wy-nav-content-wrap,\n.wy-nav-content {\n background: transparent !important;\n}\n\n.wy-side-nav-search {\n background-color: transparent !important;\n color: var(--color-a) !important;\n box-shadow: 0 4px 4px 0 var(--color-a);\n border-bottom: 1px solid var(--color-d) !important;\n}\n\n.wy-side-nav-search svg {\n color: var(--color-a) !important;\n}\n\n.wy-nav-top {\n background-color: transparent !important;\n color: var(--color-a) !important;\n}\n\n.wy-nav-top a {\n color: var(--color-a) !important;\n}\n\n.wy-breadcrumbs a.icon-home:before {\n content: \"Documentation\";\n font-family: \"Overpass\", sans-serif;\n}\n\n.rst-content table.docutils thead {\n color: var(--color-a);\n}\n\ncode.docutils.literal.notranslate {\n padding: 2px 4px;\n font-size: 0.875em;\n font-family: \"Overpass Mono\", monospace;\n background: var(--white);\n color: var(--color-c);\n border: 0px;\n}\n\ndt code.docutils.literal.notranslate {\n background: none;\n}\n\n.wy-nav-content {\n color: var(--color-a);\n}\n\n/* .rst-content a:not(:visited) { */\n/* color: var(--color-b) !important; */\n/* } */\n\n.rst-content a:visited {\n color: var(--color-c) !important;\n}\n\n.rst-content a {\n text-decoration: underline;\n}\n\n.rst-content a:where(:focus, :focus-visible, :hover) {\n color: var(--color-d) !important;\n}\n\n.wy-side-scroll a {\n color: var(--color-a);\n background: transparent;\n font-size: 1rem;\n line-height: 125%;\n}\n\n.wy-menu-vertical li.current a,\n.wy-menu-vertical li.current li a,\n.wy-menu-vertical li.current li a code {\n border: none;\n color: var(--color-a);\n}\n\nul.current ul,\n.wy-menu-vertical li.current a:hover,\n.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,\n.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,\n.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,\n.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,\n.wy-menu-vertical li.current {\n background: var(--menu-bg) !important;\n}\n\n.wy-menu.wy-menu-vertical>ul {\n margin-bottom: 3rem;\n}\n\n.wy-menu.wy-menu-vertical>p {\n color: var(--color-c);\n}\n\n.wy-menu-vertical li.on a,\n.wy-menu-vertical li.current>a {\n background: var(--menu-bg) !important;\n border-bottom: 0px !important;\n border-top: 0px !important;\n}\n\n.btn {\n border-radius: 0;\n text-decoration: none !important;\n}\n\n.wy-breadcrumbs-aside a,\n.wy-breadcrumbs-aside a:visited,\na.fa.fa-github,\na.fa.fa-github:visited,\na.fa.fa-github:not(:visited),\na.btn.btn-neutral:visited,\na.btn.btn-neutral:not(:visited),\na.btn.btn-neutral {\n background: transparent !important;\n color: var(--color-a) !important;\n border: 2px solid var(--color-a) !important;\n text-decoration: none;\n}\n\n.rst-content .remix-link-container a.remix-link:hover,\n.wy-breadcrumbs-aside a:hover,\na.fa.fa-github:hover,\na.btn.btn-neutral:hover {\n background: var(--white) !important;\n color: var(--color-b) !important;\n border-color: var(--color-b) !important;\n}\n\nfooter .rst-footer-buttons {\n display: flex;\n justify-content: center;\n gap: 2rem;\n}\n\n/**\n * Customization for the unified layout\n */\n\n/* Site wrapper, and two children: header and rest */\n.unified-wrapper {\n position: relative;\n display: flex;\n flex-direction: column;\n inset: 0;\n max-width: var(--maxWidth);\n margin-inline: auto;\n}\n\n/* Site header */\n.unified-header {\n position: fixed;\n top: 0;\n inset-inline: 0;\n z-index: 99999;\n display: flex;\n align-items: center;\n box-shadow: var(--shadow);\n}\n\n.unified-header .inner-header {\n display: flex;\n margin-inline: auto;\n width: 100%;\n max-width: var(--maxWidth);\n align-items: center;\n justify-content: space-between;\n padding-inline: var(--desktopInlinePadding);\n padding-block: 1rem;\n}\n\n.unified-header::before {\n content: \"\";\n position: absolute;\n inset: 0;\n opacity: 95%;\n background: var(--color-f);\n z-index: -1;\n backdrop-filter: blur(3px);\n}\n\n.unified-header .home-link {\n display: block;\n text-decoration: none;\n width: 25px;\n height: 40px;\n}\n\n.unified-header .home-link:hover .solidity-logo {\n transform: scale(1.1);\n transition: transform 100ms ease-in-out;\n}\n\n.unified-header img.solidity-logo {\n transform: scale(1);\n transition: transform 100ms ease-in-out;\n width: 100%;\n height: 100%;\n}\n\n.unified-header .nav-bar {\n display: flex;\n align-items: center;\n justify-content: flex-end;\n}\n\n.unified-header .nav-bar .nav-button-container {\n display: flex;\n align-items: center;\n justify-content: center;\n gap: 0.5rem;\n}\n\n.unified-header .nav-link {\n display: inline-block;\n padding-inline: 8px;\n padding-block: 4px;\n font-size: 14px;\n font-family: 'Overpass Mono', monospace;\n text-decoration: none;\n color: var(--color-a);\n letter-spacing: -0.02em;\n font-weight: 400;\n box-sizing: content-box;\n border-bottom: 1px solid transparent;\n white-space: nowrap;\n}\n\n.unified-header .nav-link.active {\n background: var(--white);\n}\n\n.unified-header .nav-link:hover {\n color: var(--color-c);\n border-bottom: 1px solid var(--color-c);\n}\n\n/* Rest: Flex-row, with two children: side bar, and content */\n.unified-wrapper .wy-grid-for-nav {\n position: relative !important;\n display: flex;\n margin-inline: auto;\n}\n\n/* First child: Side bar */\n.unified-wrapper .wy-grid-for-nav nav.wy-nav-side {\n position: fixed;\n display: flex;\n flex-direction: column;\n background: var(--color-f);\n color: var(--color-a);\n padding-bottom: unset !important;\n z-index: 10 !important;\n min-height: unset !important;\n width: var(--sideWidth) !important;\n top: var(--navHeight);\n bottom: 0;\n left: auto;\n overflow: auto;\n}\n\n.unified-wrapper .wy-grid-for-nav nav.wy-nav-side .wy-side-scroll {\n position: static !important;\n width: unset !important;\n overflow: unset !important;\n height: unset !important;\n padding-bottom: 2rem;\n}\n\n.unified-wrapper .wy-grid-for-nav nav.wy-nav-side .wy-side-scroll .wy-side-nav-search {\n margin: 0 !important;\n width: var(--sideWidth) !important;\n}\n\n.wy-nav-side,\n.wy-side-scroll,\n.wy-side-nav-search,\n.my-menu {\n width: 100% !important;\n}\n\n.wy-nav-side input[type=text] {\n font-family: \"Overpass\", sans-serif;\n border-radius: 0;\n border-color: var(--color-d);\n background: var(--white);\n box-shadow: none;\n color: var(--color-a);\n}\n\n.wy-nav-side input[type=text]::placeholder {\n font-family: \"Overpass\", sans-serif;\n color: var(--color-e);\n font-size: 16px;\n position: relative;\n top: 4px;\n}\n\n/* Second child: Content */\n.unified-wrapper .wy-grid-for-nav .wy-nav-content {\n width: 100%;\n max-width: unset !important; /* override */\n padding-inline: var(--desktopInlinePadding);\n margin-inline-start: var(--sideWidth);\n margin-top: var(--navHeight);\n}\n\n.unified-wrapper .wy-grid-for-nav .wy-nav-content .rst-content {\n max-width: min(70ch, calc(100vw - 2 * var(--desktopInlinePadding) - var(--sideWidth)));\n margin-inline: auto;\n}\n\n.unified-wrapper.menu-open .backdrop {\n opacity: 0.5;\n}\n\n.unified-wrapper .wy-nav-side,\n.unified-wrapper .rst-versions {\n left: auto;\n\n}\n\n.unified-wrapper .backdrop {\n opacity: 0;\n transition: opacity 200ms ease-in-out;\n}\n\n@media (max-width: 768px) {\n h2 {\n margin-top: 3rem;\n margin-bottom: 1rem;\n }\n\n h3 {\n margin-top: 3rem;\n margin-bottom: 1rem;\n }\n\n h4 {\n margin-top: 2rem;\n margin-bottom: 1rem;\n }\n\n /* Menu closed styles */\n .unified-header .nav-link {\n display: none;\n }\n\n .unified-header .inner-header {\n padding-inline: var(--mobileInlinePadding);\n }\n\n .unified-wrapper .wy-grid-for-nav nav.wy-nav-side {\n transform: translateX(-100%);\n transition: transform 200ms ease-in-out;\n }\n\n /* Menu open styles */\n .unified-wrapper.menu-open nav.wy-nav-side {\n transform: translateX(0);\n transition: transform 200ms ease-in-out;\n }\n\n .unified-wrapper.menu-open .rst-versions {\n position: sticky;\n bottom: 0;\n width: 100%;\n }\n\n .unified-wrapper.menu-open .backdrop {\n display: block;\n position: fixed;\n inset: 0;\n opacity: 1;\n transition: opacity 200ms ease-in-out;\n z-index: 5;\n background: #0006;\n }\n\n a.skip-to-content {\n display: none;\n }\n\n .wy-nav-content {\n margin-inline-start: 0 !important;\n }\n\n .rst-content {\n max-width: 100% !important;\n }\n\n .wy-side-scroll {\n padding-bottom: 0 !important;\n }\n}\n\nul.search .context {\n color: var(--color-a) !important;\n}\n\n.rst-versions {\n background: var(--color-f);\n}\n\n.rst-versions.shift-up {\n height: unset !important;\n max-height: unset !important;\n overflow-y: unset !important;\n}\n\n.rst-content dl:not(.docutils) dt {\n color: var(--color-a);\n background-color: #fff8;\n border-top: solid 3px #0002;\n border-inline-start: solid 3px #0002;\n padding: 2px 6px;\n}\n\n.rst-versions .rst-current-version {\n border-color: var(--color-d) !important;\n}\n\n.rst-current-version *,\n.rst-current-version .fa:before,\n.rst-current-version .fa-element {\n color: var(--color-b) !important;\n}\n\n.rst-current-version dt,\n.rst-current-version dd,\n.rst-current-version dd a,\n.rst-other-versions dl:last-of-type dt,\n.rst-other-versions dl:last-of-type dd,\n.rst-other-versions dl:last-of-type dd a {\n font-size: 14px !important;\n}\n\n.rst-other-versions {\n background: var(--white) !important;\n color: var(--color-a) !important;\n max-height: calc(100vh - var(--navHeight) - var(--currentVersionHeight));\n overflow-y: scroll;\n}\n\n.rst-other-versions a {\n text-decoration: underline;\n color: var(--color-c) !important;\n}\n\n.rst-other-versions dt {\n color: var(--color-a) !important;\n}\n\n.rst-other-versions dl {\n margin-bottom: 1.5rem !important;\n}\n\n.rst-other-versions dl:last-of-type {\n margin-top: 2rem !important;\n}\n\n/* Bottom Search */\n.wy-nav-side input[type=text],\n.rst-other-versions dl:last-of-type dd {\n width: 100%;\n}\n\n.rst-other-versions dl:last-of-type dt {\n color: var(--color-b) !important;\n}\n\n.rst-other-versions dl:last-of-type div[style*=padding],\n.rst-other-versions dl dd:first-of-type a {\n padding-inline-start: 0 !important;\n}\n\nbutton.toctree-expand {\n color: var(--black) !important;\n}\n\n/* Light/dark color mode toggle 🌓 */\nbutton.color-toggle {\n display: inline-flex;\n appearance: none;\n -webkit-box-align: center;\n align-items: center;\n -webkit-box-pack: center;\n justify-content: center;\n user-select: none;\n outline: none;\n height: 28px;\n width: 28px;\n background: none;\n border: none;\n padding: 6px;\n margin: 6px;\n transition-duration: 200ms;\n transition-property: background-color,\n color,\n fill,\n stroke,\n opacity;\n}\n\nbutton.color-toggle:focus-visible {\n outline: 2px solid var(--color-c);\n color: var(--color-c);\n}\n\nbutton.color-toggle:hover {\n color: var(--color-c);\n background: #0002;\n}\n\nbutton.color-toggle .color-toggle-icon {\n width: 100%;\n height: 100%;\n margin: 0;\n display: inline-block;\n line-height: 1em;\n -webkit-flex-shrink: 0;\n -ms-flex-negative: 0;\n flex-shrink: 0;\n vertical-align: middle;\n /* color: var(--color-a); */\n}\n\n\nbutton.mobile-menu-button {\n display: none;\n}\n\n@media (max-width: 768px) {\n nav.wy-nav-top {\n display: none;\n }\n\n button.mobile-menu-button {\n display: flex;\n }\n}\n\n\n.hidden {\n display: none;\n}\n\n#search-results .search li:first-child,\n#search-results .search li {\n border-color: var(--color-d);\n}\n\n#search-results .search li:last-child {\n border: 0px;\n}\n\n.forum-link::after {\n content: ' ↗';\n font-size: 14px;\n font-family: 'Overpass Mono', monospace;\n}\n\n.wy-breadcrumbs>li {\n padding-top: 8px;\n}\n\n.wy-breadcrumbs-aside a {\n padding: 0.5rem 0.75rem;\n font-size: 12px;\n font-family: \"'Overpass'\", sans-serif;\n font-weight: 700;\n}\n\na.skip-to-content:visited,\na.skip-to-content:not(:visited),\na.skip-to-content {\n display: block;\n pointer-events: none;\n width: fit-content;\n opacity: 0;\n transition: opacity 200ms ease-in-out;\n padding: 2px 4px;\n font-size: 14px;\n margin-inline-end: auto;\n margin-inline-start: 1.5rem;\n color: var(--color-a);\n white-space: nowrap;\n}\n\na.skip-to-content:focus {\n opacity: 1;\n transition: opacity 200ms ease-in-out;\n}\n\n#content {\n scroll-margin-top: 6rem;\n scroll-behavior: smooth;\n}\n" }, { "path": "docs/_static/css/fonts.css", "content": "@import url(\"https://fonts.cdnfonts.com/css/overpass\");\n@import url(\"https://fonts.cdnfonts.com/css/overpass-mono\");" }, { "path": "docs/_static/css/pygments.css", "content": "pre {\n line-height: 125%;\n}\n\ntd.linenos .normal {\n color: inherit;\n background-color: transparent;\n padding-left: 5px;\n padding-right: 5px;\n}\n\nspan.linenos {\n color: inherit;\n background-color: transparent;\n padding-left: 5px;\n padding-right: 5px;\n}\n\ntd.linenos .special {\n color: #000000;\n background-color: #ffffc0;\n padding-left: 5px;\n padding-right: 5px;\n}\n\nspan.linenos.special {\n color: #000000;\n background-color: #ffffc0;\n padding-left: 5px;\n padding-right: 5px;\n}\n\n.highlight .hll {\n background-color: #ffffcc\n}\n\n.highlight {\n background: #eeffcc;\n}\n\n.highlight .c {\n color: #408090;\n font-style: italic\n}\n\n/* Comment */\n.highlight .err {\n border: 1px solid #FF0000\n}\n\n/* Error */\n.highlight .k {\n color: #007020;\n font-weight: bold\n}\n\n/* Keyword */\n.highlight .o {\n color: #666666\n}\n\n/* Operator */\n.highlight .ch {\n color: #408090;\n font-style: italic\n}\n\n/* Comment.Hashbang */\n.highlight .cm {\n color: #408090;\n font-style: italic\n}\n\n/* Comment.Multiline */\n.highlight .cp {\n color: #007020\n}\n\n/* Comment.Preproc */\n.highlight .cpf {\n color: #408090;\n font-style: italic\n}\n\n/* Comment.PreprocFile */\n.highlight .c1 {\n color: #408090;\n font-style: italic\n}\n\n/* Comment.Single */\n.highlight .cs {\n color: #408090;\n background-color: #fff0f0\n}\n\n/* Comment.Special */\n.highlight .gd {\n color: #A00000\n}\n\n/* Generic.Deleted */\n.highlight .ge {\n font-style: italic\n}\n\n/* Generic.Emph */\n.highlight .gr {\n color: #FF0000\n}\n\n/* Generic.Error */\n.highlight .gh {\n color: #000080;\n font-weight: bold\n}\n\n/* Generic.Heading */\n.highlight .gi {\n color: #00A000\n}\n\n/* Generic.Inserted */\n.highlight .go {\n color: #333333\n}\n\n/* Generic.Output */\n.highlight .gp {\n color: #c65d09;\n font-weight: bold\n}\n\n/* Generic.Prompt */\n.highlight .gs {\n font-weight: bold\n}\n\n/* Generic.Strong */\n.highlight .gu {\n color: #800080;\n font-weight: bold\n}\n\n/* Generic.Subheading */\n.highlight .gt {\n color: #0044DD\n}\n\n/* Generic.Traceback */\n.highlight .kc {\n color: #007020;\n font-weight: bold\n}\n\n/* Keyword.Constant */\n.highlight .kd {\n color: #007020;\n font-weight: bold\n}\n\n/* Keyword.Declaration */\n.highlight .kn {\n color: #007020;\n font-weight: bold\n}\n\n/* Keyword.Namespace */\n.highlight .kp {\n color: #007020\n}\n\n/* Keyword.Pseudo */\n.highlight .kr {\n color: #007020;\n font-weight: bold\n}\n\n/* Keyword.Reserved */\n.highlight .kt {\n color: #902000\n}\n\n/* Keyword.Type */\n.highlight .m {\n color: #208050\n}\n\n/* Literal.Number */\n.highlight .s {\n color: #4070a0\n}\n\n/* Literal.String */\n.highlight .na {\n color: #4070a0\n}\n\n/* Name.Attribute */\n.highlight .nb {\n color: #007020\n}\n\n/* Name.Builtin */\n.highlight .nc {\n color: #0e84b5;\n font-weight: bold\n}\n\n/* Name.Class */\n.highlight .no {\n color: #60add5\n}\n\n/* Name.Constant */\n.highlight .nd {\n color: #555555;\n font-weight: bold\n}\n\n/* Name.Decorator */\n.highlight .ni {\n color: #d55537;\n font-weight: bold\n}\n\n/* Name.Entity */\n.highlight .ne {\n color: #007020\n}\n\n/* Name.Exception */\n.highlight .nf {\n color: #06287e\n}\n\n/* Name.Function */\n.highlight .nl {\n color: #002070;\n font-weight: bold\n}\n\n/* Name.Label */\n.highlight .nn {\n color: #0e84b5;\n font-weight: bold\n}\n\n/* Name.Namespace */\n.highlight .nt {\n color: #062873;\n font-weight: bold\n}\n\n/* Name.Tag */\n.highlight .nv {\n color: #bb60d5\n}\n\n/* Name.Variable */\n.highlight .ow {\n color: #007020;\n font-weight: bold\n}\n\n/* Operator.Word */\n.highlight .w {\n color: #bbbbbb\n}\n\n/* Text.Whitespace */\n.highlight .mb {\n color: #208050\n}\n\n/* Literal.Number.Bin */\n.highlight .mf {\n color: #208050\n}\n\n/* Literal.Number.Float */\n.highlight .mh {\n color: #208050\n}\n\n/* Literal.Number.Hex */\n.highlight .mi {\n color: #208050\n}\n\n/* Literal.Number.Integer */\n.highlight .mo {\n color: #208050\n}\n\n/* Literal.Number.Oct */\n.highlight .sa {\n color: #4070a0\n}\n\n/* Literal.String.Affix */\n.highlight .sb {\n color: #4070a0\n}\n\n/* Literal.String.Backtick */\n.highlight .sc {\n color: #4070a0\n}\n\n/* Literal.String.Char */\n.highlight .dl {\n color: #4070a0\n}\n\n/* Literal.String.Delimiter */\n.highlight .sd {\n color: #4070a0;\n font-style: italic\n}\n\n/* Literal.String.Doc */\n.highlight .s2 {\n color: #4070a0\n}\n\n/* Literal.String.Double */\n.highlight .se {\n color: #4070a0;\n font-weight: bold\n}\n\n/* Literal.String.Escape */\n.highlight .sh {\n color: #4070a0\n}\n\n/* Literal.String.Heredoc */\n.highlight .si {\n color: #70a0d0;\n font-style: italic\n}\n\n/* Literal.String.Interpol */\n.highlight .sx {\n color: #c65d09\n}\n\n/* Literal.String.Other */\n.highlight .sr {\n color: #235388\n}\n\n/* Literal.String.Regex */\n.highlight .s1 {\n color: #4070a0\n}\n\n/* Literal.String.Single */\n.highlight .ss {\n color: #517918\n}\n\n/* Literal.String.Symbol */\n.highlight .bp {\n color: #007020\n}\n\n/* Name.Builtin.Pseudo */\n.highlight .fm {\n color: #06287e\n}\n\n/* Name.Function.Magic */\n.highlight .vc {\n color: #bb60d5\n}\n\n/* Name.Variable.Class */\n.highlight .vg {\n color: #bb60d5\n}\n\n/* Name.Variable.Global */\n.highlight .vi {\n color: #bb60d5\n}\n\n/* Name.Variable.Instance */\n.highlight .vm {\n color: #bb60d5\n}\n\n/* Name.Variable.Magic */\n.highlight .il {\n color: #208050\n}\n\n/* Literal.Number.Integer.Long */" }, { "path": "docs/_static/css/toggle.css", "content": "input[type=checkbox] {\n visibility: hidden;\n height: 0;\n width: 0;\n margin: 0;\n}\n\n.rst-versions .rst-current-version {\n padding: 10px;\n display: flex;\n justify-content: space-between;\n background-color: var(--color-f);\n border-top: 1px solid var(--color-c);\n}\n\n.fa-caret-down,\n.fa-book {\n color: var(--color-a) !important;\n}\n\n.rst-versions .rst-current-version .fa-book,\n.rst-versions .rst-current-version .fa-v,\n.rst-versions .rst-current-version .fa-caret-down {\n height: 24px;\n line-height: 24px;\n vertical-align: middle;\n}\n\n.rst-versions .rst-current-version .fa-element {\n width: 80px;\n text-align: center;\n}\n\n.rst-versions .rst-current-version .fa-book {\n text-align: left;\n}\n\n.rst-versions .rst-current-version .fa-v {\n color: #27AE60;\n text-align: right;\n}\n\nlabel {\n margin: 0 auto;\n display: inline-block;\n justify-content: center;\n align-items: right;\n border-radius: 100px;\n position: relative;\n cursor: pointer;\n text-indent: -9999px;\n width: 50px;\n height: 21px;\n background: #000;\n}\n\nlabel:after {\n border-radius: 50%;\n position: absolute;\n content: '';\n background: #fff;\n width: 15px;\n height: 15px;\n top: 3px;\n left: 3px;\n transition: ease-in-out 200ms;\n}\n\ninput:checked+label {\n background: #3a7ca8;\n}\n\ninput:checked+label:after {\n left: calc(100% - 5px);\n transform: translateX(-100%);\n}\n\nhtml.transition,\nhtml.transition *,\nhtml.transition *:before,\nhtml.transition *:after {\n transition: ease-in-out 200ms !important;\n transition-delay: 0 !important;\n}\n\n.wy-menu-vertical a:hover {\n background-color: #0002;\n}\n\nbody {\n font-weight: 300;\n letter-spacing: 0.5px;\n}" }, { "path": "docs/_static/js/constants.js", "content": "// Site URL\nconst SITE_URL = \"https://docs.soliditylang.org\"\nconst { origin, pathname } = location;\nconst pathSplit = pathname.split(\"/\");\nconst rootPath = origin.includes(SITE_URL) && pathSplit.length > 3 ? pathSplit.splice(1, 2).join(\"/\") : ''\nconst ROOT_URL = `${origin}/${rootPath}`;\n\n// Color mode constants\nconst [DARK, LIGHT] = [\"dark\", \"light\"];\nconst LIGHT_LOGO_PATH = `${ROOT_URL}/_static/img/logo.svg`;\nconst DARK_LOGO_PATH = `${ROOT_URL}/_static/img/logo-dark.svg`;\nconst SUN_ICON_PATH = `${ROOT_URL}/_static/img/sun.svg`;\nconst MOON_ICON_PATH = `${ROOT_URL}/_static/img/moon.svg`;\nconst LIGHT_HAMBURGER_PATH = `${ROOT_URL}/_static/img/hamburger-light.svg`;\nconst DARK_HAMBURGER_PATH = `${ROOT_URL}/_static/img/hamburger-dark.svg`;\nconst COLOR_TOGGLE_ICON_CLASS = \"color-toggle-icon\";\nconst SOLIDITY_LOGO_CLASS = \"solidity-logo\";\nconst LS_COLOR_SCHEME = \"color-scheme\";\n\n// Solidity navigation constants\nconst SOLIDITY_HOME_URL = \"https://soliditylang.org\";\nconst BLOG_URL = `${SOLIDITY_HOME_URL}/blog`;\nconst DOCS_URL = \"/\";\nconst USE_CASES_PATH = `${SOLIDITY_HOME_URL}/use-cases`;\nconst CONTRIBUTE_PATH = `/en/latest/contributing.html`;\nconst ABOUT_PATH = `${SOLIDITY_HOME_URL}/about`;\nconst FORUM_URL = \"https://forum.soliditylang.org/\";\nconst NAV_LINKS = [\n { name: window.NAV_LINKS.blog, href: BLOG_URL },\n { name: window.NAV_LINKS.documentation, href: DOCS_URL },\n { name: window.NAV_LINKS.use_cases, href: USE_CASES_PATH },\n { name: window.NAV_LINKS.contribute, href: CONTRIBUTE_PATH },\n { name: window.NAV_LINKS.about, href: ABOUT_PATH },\n { name: window.NAV_LINKS.forum, href: FORUM_URL },\n];\n\nconst MOBILE_MENU_TOGGLE_CLASS = \"shift\";\nconst WRAPPER_CLASS = \"unified-wrapper\";\n" }, { "path": "docs/_static/js/initialize.js", "content": "const getLogoSrc = (isDark) => (isDark ? DARK_LOGO_PATH : LIGHT_LOGO_PATH);\n\nconst getModeIconSrc = (isDark) => (isDark ? SUN_ICON_PATH : MOON_ICON_PATH);\n\nconst getMenuIconSrc = (isDark) =>\n isDark ? DARK_HAMBURGER_PATH : LIGHT_HAMBURGER_PATH;\n\nfunction addFooterNote() {\n const contentInfo = document.querySelector(\"div[role=contentinfo]\");\n const footerNote = document.createElement(\"p\");\n footerNote.classList.add(\"footer-note\");\n footerNote.innerHTML =\n 'Customized with ❤️ by the ethereum.org team.';\n contentInfo.parentNode.insertBefore(footerNote, contentInfo.nextSibling);\n}\n\nfunction rearrangeDom() {\n const bodyDivs = document.querySelectorAll(\"body>div\");\n bodyDivs.forEach((div) => div.remove());\n const wrapperDiv = document.createElement(\"div\");\n wrapperDiv.classList.add(WRAPPER_CLASS);\n bodyDivs.forEach((div) => wrapperDiv.appendChild(div));\n document.body.prepend(wrapperDiv);\n\n const rstVersions = document.querySelector(\".rst-versions\");\n const wyNavSide = document.querySelector(\"nav.wy-nav-side\");\n // NOTE: Since RTD migration to addons, `.rst-versions` is no longer present in the DOM.\n // The following code is kept for compatibility with older versions.\n // See: https://github.com/readthedocs/readthedocs.org/issues/11474\n if (rstVersions && wyNavSide) {\n rstVersions.remove();\n wyNavSide.appendChild(rstVersions);\n }\n const backdrop = document.createElement(\"div\");\n backdrop.classList.add(\"backdrop\");\n wrapperDiv.appendChild(backdrop);\n\n const content = document.querySelector(\".wy-nav-content\");\n if (content) {\n content.id = \"content\";\n document.querySelector(\"section.wy-nav-content-wrap\")?.remove();\n document.querySelector(\".wy-grid-for-nav\")?.appendChild(content);\n }\n}\n\nfunction buildHeader() {\n const isDarkMode = localStorage.getItem(LS_COLOR_SCHEME) == DARK;\n\n const header = document.createElement(\"div\");\n header.classList.add(\"unified-header\");\n document.querySelector(`.${WRAPPER_CLASS}`).prepend(header);\n\n const innerHeader = document.createElement(\"div\");\n innerHeader.classList.add(\"inner-header\");\n header.appendChild(innerHeader);\n\n const homeLink = document.createElement(\"a\");\n homeLink.classList.add(\"home-link\");\n homeLink.href = SOLIDITY_HOME_URL;\n homeLink.ariaLabel = \"Solidity home\";\n innerHeader.appendChild(homeLink);\n\n const logo = document.createElement(\"img\");\n logo.classList.add(SOLIDITY_LOGO_CLASS);\n logo.src = getLogoSrc(isDarkMode);\n logo.alt = \"Solidity logo\";\n homeLink.appendChild(logo);\n\n const skipToContent = document.createElement(\"a\");\n skipToContent.classList.add(\"skip-to-content\");\n skipToContent.href = \"#content\";\n skipToContent.innerText = \"{skip to content}\";\n innerHeader.appendChild(skipToContent);\n\n const navBar = document.createElement(\"nav\");\n navBar.classList.add(\"nav-bar\");\n innerHeader.appendChild(navBar);\n\n const linkElements = NAV_LINKS.map(({ name, href }) => {\n const link = document.createElement(\"a\");\n link.classList.add(\"nav-link\");\n link.setAttribute(\"key\", name);\n link.setAttribute(\"href\", href);\n link.setAttribute(\"aria-label\", name);\n if (href === FORUM_URL) {\n link.classList.add(\"forum-link\");\n link.setAttribute(\"target\", \"_blank\");\n link.setAttribute(\"rel\", \"noopener noreferrer\");\n }\n link.innerText = name;\n return link;\n });\n linkElements.forEach((link) => navBar.appendChild(link));\n\n // Flex wrapper for color mode and mobile menu buttons\n const navButtonContainer = document.createElement(\"div\");\n navButtonContainer.classList.add(\"nav-button-container\");\n navBar.appendChild(navButtonContainer);\n\n // Build color toggle\n const toggleIcon = document.createElement(\"img\");\n toggleIcon.classList.add(COLOR_TOGGLE_ICON_CLASS);\n toggleIcon.src = getModeIconSrc(isDarkMode);\n toggleIcon.alt = \"Color mode toggle icon\";\n toggleIcon.setAttribute(\"aria-hidden\", \"true\");\n toggleIcon.setAttribute(\"key\", \"toggle icon\");\n const colorModeButton = document.createElement(\"button\");\n colorModeButton.classList.add(\"color-toggle\");\n colorModeButton.setAttribute(\"type\", \"button\");\n colorModeButton.setAttribute(\"aria-label\", \"Toggle light dark mode\");\n colorModeButton.setAttribute(\"key\", \"color mode button\");\n colorModeButton.addEventListener(\"click\", toggleColorMode);\n colorModeButton.appendChild(toggleIcon);\n navButtonContainer.appendChild(colorModeButton);\n\n // Build mobile hamburger menu\n const menuIcon = document.createElement(\"img\");\n menuIcon.classList.add(COLOR_TOGGLE_ICON_CLASS);\n menuIcon.src = getMenuIconSrc(isDarkMode);\n menuIcon.alt = \"Toggle menu\";\n menuIcon.setAttribute(\"aria-hidden\", \"true\");\n menuIcon.setAttribute(\"key\", \"menu icon\");\n const menuButton = document.createElement(\"button\");\n menuButton.classList.add(\"color-toggle\");\n menuButton.classList.add(\"mobile-menu-button\");\n menuButton.setAttribute(\"type\", \"button\");\n menuButton.setAttribute(\"aria-label\", \"Toggle menu\");\n menuButton.setAttribute(\"key\", \"menu button\");\n menuButton.addEventListener(\"click\", toggleMenu);\n menuButton.appendChild(menuIcon);\n navButtonContainer.appendChild(menuButton);\n}\n\nconst updateActiveNavLink = () => {\n const navLinks = document.querySelectorAll(\".unified-header .nav-link\");\n navLinks.forEach((link) => {\n const href = link.getAttribute(\"href\");\n if (document.documentURI.includes(\"contributing.html\")) {\n link.classList[href.includes(\"contributing.html\") ? \"add\" : \"remove\"](\n \"active\"\n );\n } else {\n link.classList[document.documentURI.includes(href) ? \"add\" : \"remove\"](\n \"active\"\n );\n }\n });\n};\n\ndocument.addEventListener(\"locationchange\", updateActiveNavLink);\n\nfunction updateGitHubEditPath() {\n // Replaces the version number in the GitHub edit path with \"develop\" if it exists.\n // This is to ensure that the edit path always points to the `develop` branch instead of the specific version branch.\n // Note that it will fail silently if the anchor element is not found, i.e. the page is not editable or\n // if the sphinx_rtd_theme is updated to a version that changes the anchor element.\n // See: https://github.com/readthedocs/sphinx_rtd_theme/blob/a1c2147b17cbf0e57b7d7a6450ad4d9a5ff362cf/sphinx_rtd_theme/breadcrumbs.html#L35\n // TODO: We should consider a more robust way to handle this in the future.\n const gitHubEditAnchor = document.querySelector(\".wy-breadcrumbs-aside > a\");\n if (!gitHubEditAnchor) return;\n\n const url = new URL(gitHubEditAnchor.href);\n const split = url.pathname.split(\"/\");\n const versionIndex = split.indexOf(\"blob\") + 1;\n split[versionIndex] = \"develop\";\n url.pathname = split.join(\"/\");\n gitHubEditAnchor.setAttribute(\"href\", url.toString());\n gitHubEditAnchor.setAttribute(\"target\", \"_blank\");\n gitHubEditAnchor.setAttribute(\"rel\", \"noopener noreferrer\");\n}\n\nfunction initialize() {\n // Rearrange DOM elements for styling\n rearrangeDom();\n\n // Check localStorage for existing color scheme preference\n var prefersDark = localStorage.getItem(LS_COLOR_SCHEME) == DARK;\n // Check link for search param \"color\"... it may be \"light\" or \"dark\"\n var urlParams = new URLSearchParams(window.location.search);\n if (urlParams.size > 0) {\n // This is used for color mode continuity between the main Solidity Lang site and the docs\n var colorSchemeParam = urlParams.get(\"color\");\n // If present, overwrite prefersDark accordingly\n if (colorSchemeParam) {\n prefersDark = colorSchemeParam == DARK;\n }\n\n // Remove \"color\" search param from URL\n const { location, title } = document;\n const { pathname, origin, search, hash } = location;\n const newSearchParams = new URLSearchParams(search);\n newSearchParams.delete(\"color\");\n const sanitizedSearch =\n newSearchParams.size < 1 ? \"\" : \"?\" + newSearchParams.toString();\n window.history.replaceState(\n origin,\n title,\n pathname + sanitizedSearch + hash\n );\n }\n\n // In case none existed, establish localStorage color scheme preference\n var mode = prefersDark ? DARK : LIGHT;\n localStorage.setItem(LS_COLOR_SCHEME, mode);\n\n // Select the root element and set the style attribute to denote color-scheme attribute\n document\n .querySelector(\":root\")\n .setAttribute(\"style\", `--color-scheme: ${mode}`);\n\n // NOTE: Since RTD migration to addons, the elements below are no longer present in the DOM.\n // The following code is kept for compatibility with older versions.\n // Remove old input and RTD logo anchor element\n document.querySelector(\"input[name=mode]\")?.remove();\n document.querySelector(\"label[for=switch]\")?.remove();\n document.querySelector(\".wy-side-nav-search > a\")?.remove();\n\n // Add footer note\n addFooterNote();\n\n // Build header\n buildHeader();\n\n // Close menu\n toggleMenu({ force: false });\n\n // Update active nav link\n updateActiveNavLink();\n\n // Update GitHub edit path to direct to `develop` branch\n updateGitHubEditPath();\n}\n\ndocument.addEventListener(\"DOMContentLoaded\", initialize);\n\nconst handleClick = (e) => {\n if (e.target.closest(\".backdrop\")) {\n toggleMenu({ force: false });\n }\n\n if (e.target.closest(\"a\")) {\n const target = e.target.closest(\"a\");\n const href = target.getAttribute(\"href\");\n if (href.includes(SOLIDITY_HOME_URL)) {\n const url = new URL(href);\n const params = new URLSearchParams(url.search);\n params.set(\"color\", localStorage.getItem(LS_COLOR_SCHEME));\n url.search = params.toString();\n target.setAttribute(\"href\", url.toString());\n }\n }\n};\ndocument.addEventListener(\"click\", handleClick);\n\nconst handleKeyDown = (e) => {\n if (e.metaKey && e.key === \"k\") {\n document.querySelector(\"#rtd-search-form input\")?.focus();\n } else if (e.key === \"Escape\") {\n toggleMenu({ force: false });\n }\n if (e.metaKey && e.code === \"Backslash\") {\n toggleColorMode();\n }\n};\ndocument.addEventListener(\"keydown\", handleKeyDown);\n" }, { "path": "docs/_static/js/toggle.js", "content": "function toggleColorMode() {\n // Check localStorage for previous color scheme preference, assign the opposite\n var newMode = localStorage.getItem(LS_COLOR_SCHEME) == DARK ? LIGHT : DARK;\n\n // Update localStorage with new color scheme preference\n localStorage.setItem(LS_COLOR_SCHEME, newMode);\n\n // Update the root element with the new color scheme preference\n document\n .querySelector(\":root\")\n .setAttribute(\"style\", `--color-scheme: ${newMode}`);\n\n // Update logo\n document\n .querySelector(`img.${SOLIDITY_LOGO_CLASS}`)\n .setAttribute(\"src\", newMode === LIGHT ? LIGHT_LOGO_PATH : DARK_LOGO_PATH);\n\n // Update color mode toggle icon\n document\n .querySelector(`img.${COLOR_TOGGLE_ICON_CLASS}`)\n .setAttribute(\"src\", newMode === LIGHT ? MOON_ICON_PATH : SUN_ICON_PATH);\n\n // Update hamburger menu icon color\n document\n .querySelector(\"button.mobile-menu-button img\")\n .setAttribute(\n \"src\",\n newMode === LIGHT ? LIGHT_HAMBURGER_PATH : DARK_HAMBURGER_PATH\n );\n}\n\nfunction toggleMenu(options = {}) {\n const handleClassToggle = ({ classList }, className) => {\n if (typeof options.force !== \"undefined\") {\n classList.toggle(className, options.force);\n } else {\n classList.toggle(className);\n }\n };\n document\n .querySelectorAll('[data-toggle=\"rst-versions\"]')\n .forEach((e) => handleClassToggle(e, MOBILE_MENU_TOGGLE_CLASS));\n document\n .querySelectorAll('[data-toggle=\"wy-nav-shift\"]')\n .forEach((e) => handleClassToggle(e, MOBILE_MENU_TOGGLE_CLASS));\n handleClassToggle(document.querySelector(`.${WRAPPER_CLASS}`), \"menu-open\");\n}\n" }, { "path": "docs/_templates/footer.html", "content": "{% extends \"!footer.html\" %}\n\n{% block extrafooter %}\n

\n Credits and attribution.\n

\n{% endblock %}\n" }, { "path": "docs/_templates/layout.html", "content": "{% extends \"!layout.html\" %}\n\n{% block scripts %}\n \n {{ super() }}\n{% endblock %}\n\n{% block menu %}\n {{ super() }}\n \n{% endblock %}\n" }, { "path": "docs/_templates/versions.html", "content": "{# Add rst-badge after rst-versions for small badge style. #}\n
\n \n RTD \n\n \n \n \n \n\n v: {{ current_version }} \n\n \n
\n
\n
{{ _('Downloads') }}
{% for type, url in downloads %}\n
{{ type }}
\n {% endfor %}\n
\n
\n
{{ _('Versions') }}
{% for slug, url in versions %}\n
{{ slug }}
\n {% endfor %}\n
\n
\n {# Translators: The phrase \"Read the Docs\" is not translated #}\n
{{ _('On Read the Docs') }}
\n
\n {{ _('Project Home') }}\n
\n
\n {{ _('Builds') }}\n
\n
\n
\n
\n" }, { "path": "docs/abi-spec.rst", "content": ".. index:: abi, application binary interface\n\n.. _ABI:\n\n**************************\nContract ABI Specification\n**************************\n\nBasic Design\n============\n\nThe Contract Application Binary Interface (ABI) is the standard way to interact with contracts in the Ethereum ecosystem, both\nfrom outside the blockchain and for contract-to-contract interaction. Data is encoded according to its type,\nas described in this specification. The encoding is not self describing and thus requires a schema in order to decode.\n\nWe assume that the interface functions of a contract are strongly typed, known at compilation time and static.\nWe assume that all contracts will have the interface definitions of any contracts they call available at compile-time.\n\nThis specification does not address contracts whose interface is dynamic or otherwise known only at run-time. Also, the ABI specification for libraries is :ref:`slightly different `.\n\n.. _abi_function_selector:\n.. index:: ! selector; of a function\n\nFunction Selector\n=================\n\nThe first four bytes of the call data for a function call specifies the function to be called. It is the\nfirst (left, high-order in big-endian) four bytes of the Keccak-256 hash of the signature of\nthe function. The signature is defined as the canonical expression of the basic prototype without data\nlocation specifier, i.e.\nthe function name with the parenthesised list of parameter types. Parameter types are split by a single\ncomma — no spaces are used.\n\n.. note::\n The return type of a function is not part of this signature. In\n :ref:`Solidity's function overloading ` return types are not considered.\n The reason is to keep function call resolution context-independent.\n The :ref:`JSON description of the ABI` however contains both inputs and outputs.\n\nArgument Encoding\n=================\n\nStarting from the fifth byte, the encoded arguments follow. This encoding is also used in\nother places, e.g. the return values and also event arguments are encoded in the same way,\nwithout the four bytes specifying the function.\n\nTypes\n=====\n\nNote that the library ABIs can take types different than below e.g. for non-storage structs. See :ref:`library selectors ` for details.\n\nThe following elementary types exist:\n\n- ``uint``: unsigned integer type of ``M`` bits, ``0 < M <= 256``, ``M % 8 == 0``. e.g. ``uint32``, ``uint8``, ``uint256``.\n\n- ``int``: two's complement signed integer type of ``M`` bits, ``0 < M <= 256``, ``M % 8 == 0``.\n\n- ``address``: equivalent to ``uint160``, except for the assumed interpretation and language typing.\n For computing the function selector, ``address`` is used.\n\n- ``uint``, ``int``: synonyms for ``uint256``, ``int256`` respectively. For computing the function\n selector, ``uint256`` and ``int256`` have to be used.\n\n- ``bool``: equivalent to ``uint8`` restricted to the values 0 and 1. For computing the function selector, ``bool`` is used.\n\n- ``fixedx``: signed fixed-point decimal number of ``M`` bits, ``8 <= M <= 256``,\n ``M % 8 == 0``, and ``0 < N <= 80``, which denotes the value ``v`` as ``v / (10 ** N)``.\n\n- ``ufixedx``: unsigned variant of ``fixedx``.\n\n- ``fixed``, ``ufixed``: synonyms for ``fixed128x18``, ``ufixed128x18`` respectively. For\n computing the function selector, ``fixed128x18`` and ``ufixed128x18`` have to be used.\n\n- ``bytes``: binary type of ``M`` bytes, ``0 < M <= 32``.\n\n- ``function``: an address (20 bytes) followed by a function selector (4 bytes). Encoded identical to ``bytes24``.\n\nThe following (fixed-size) array type exists:\n\n- ``[M]``: a fixed-length array of ``M`` elements, ``M >= 0``, of the given type.\n\n .. note::\n\n While this ABI specification can express fixed-length arrays with zero elements, they're not supported by the compiler.\n\nThe following non-fixed-size types exist:\n\n- ``bytes``: dynamic sized byte sequence.\n\n- ``string``: dynamic sized unicode string assumed to be UTF-8 encoded.\n\n- ``[]``: a variable-length array of elements of the given type.\n\nTypes can be combined to a tuple by enclosing them inside parentheses, separated by commas:\n\n- ``(T1,T2,...,Tn)``: tuple consisting of the types ``T1``, ..., ``Tn``, ``n >= 0``\n\nIt is possible to form tuples of tuples, arrays of tuples and so on. It is also possible to form zero-tuples (where ``n == 0``).\n\nMapping Solidity to ABI types\n-----------------------------\n\nSolidity supports all the types presented above with the same names with the\nexception of tuples. On the other hand, some Solidity types are not supported\nby the ABI. The following table shows on the left column Solidity types that\nare not part of the ABI, and on the right column the ABI types that represent\nthem.\n\n+-------------------------------+-----------------------------------------------------------------------------+\n| Solidity | ABI |\n+===============================+=============================================================================+\n|:ref:`address payable
`|``address`` |\n+-------------------------------+-----------------------------------------------------------------------------+\n|:ref:`contract` |``address`` |\n+-------------------------------+-----------------------------------------------------------------------------+\n|:ref:`enum` |``uint8`` |\n+-------------------------------+-----------------------------------------------------------------------------+\n|:ref:`user defined value types |its underlying value type |\n|` | |\n+-------------------------------+-----------------------------------------------------------------------------+\n|:ref:`struct` |``tuple`` |\n+-------------------------------+-----------------------------------------------------------------------------+\n\n.. warning::\n Before version ``0.8.0`` enums could have more than 256 members and were represented by the\n smallest integer type just big enough to hold the value of any member.\n\nDesign Criteria for the Encoding\n================================\n\nThe encoding is designed to have the following properties, which are especially useful if some arguments are nested arrays:\n\n1. The number of reads necessary to access a value is at most the depth of the value\n inside the argument array structure, i.e. four reads are needed to retrieve ``a_i[k][l][r]``. In a\n previous version of the ABI, the number of reads scaled linearly with the total number of dynamic\n parameters in the worst case.\n\n2. The data of a variable or an array element is not interleaved with other data and it is\n relocatable, i.e. it only uses relative \"addresses\".\n\n\nFormal Specification of the Encoding\n====================================\n\nWe distinguish static and dynamic types. Static types are encoded in-place and dynamic types are\nencoded at a separately allocated location after the current block.\n\n**Definition:** The following types are called \"dynamic\":\n\n* ``bytes``\n* ``string``\n* ``T[]`` for any ``T``\n* ``T[k]`` for any dynamic ``T`` and any ``k >= 0``\n* ``(T1,...,Tk)`` if ``Ti`` is dynamic for some ``1 <= i <= k``\n\nAll other types are called \"static\".\n\n**Definition:** ``len(a)`` is the number of bytes in a binary string ``a``.\nThe type of ``len(a)`` is assumed to be ``uint256``.\n\nWe define ``enc``, the actual encoding, as a mapping of values of the ABI types to binary strings such\nthat ``len(enc(X))`` depends on the value of ``X`` if and only if the type of ``X`` is dynamic.\n\n**Definition:** For any ABI value ``X``, we recursively define ``enc(X)``, depending\non the type of ``X`` being\n\n- ``(T1,...,Tk)`` for ``k >= 0`` and any types ``T1``, ..., ``Tk``\n\n ``enc(X) = head(X(1)) ... head(X(k)) tail(X(1)) ... tail(X(k))``\n\n where ``X = (X(1), ..., X(k))`` and\n ``head`` and ``tail`` are defined for ``Ti`` as follows:\n\n if ``Ti`` is static:\n\n ``head(X(i)) = enc(X(i))`` and ``tail(X(i)) = \"\"`` (the empty string)\n\n otherwise, i.e. if ``Ti`` is dynamic:\n\n ``head(X(i)) = enc(len( head(X(1)) ... head(X(k)) tail(X(1)) ... tail(X(i-1)) ))``\n ``tail(X(i)) = enc(X(i))``\n\n Note that in the dynamic case, ``head(X(i))`` is well-defined since the lengths of\n the head parts only depend on the types and not the values. The value of ``head(X(i))`` is the offset\n of the beginning of ``tail(X(i))`` relative to the start of ``enc(X)``.\n\n- ``T[k]`` for any ``T`` and ``k``:\n\n ``enc(X) = enc((X[0], ..., X[k-1]))``\n\n i.e. it is encoded as if it were a tuple with ``k`` elements\n of the same type.\n\n- ``T[]`` where ``X`` has ``k`` elements (``k`` is assumed to be of type ``uint256``):\n\n ``enc(X) = enc(k) enc((X[0], ..., X[k-1]))``\n\n 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\n the number of elements.\n\n- ``bytes``, of length ``k`` (which is assumed to be of type ``uint256``):\n\n ``enc(X) = enc(k) pad_right(X)``, i.e. the number of bytes is encoded as a\n ``uint256`` followed by the actual value of ``X`` as a byte sequence, followed by\n the minimum number of zero-bytes such that ``len(enc(X))`` is a multiple of 32.\n\n- ``string``:\n\n ``enc(X) = enc(enc_utf8(X))``, i.e. ``X`` is UTF-8 encoded and this value is interpreted\n as of ``bytes`` type and encoded further. Note that the length used in this subsequent\n encoding is the number of bytes of the UTF-8 encoded string, not its number of characters.\n\n- ``uint``: ``enc(X)`` is the big-endian encoding of ``X``, padded on the higher-order\n (left) side with zero-bytes such that the length is 32 bytes.\n- ``address``: as in the ``uint160`` case\n- ``int``: ``enc(X)`` is the big-endian two's complement encoding of ``X``, padded on the higher-order (left) side with ``0xff`` bytes for negative ``X`` and with zero-bytes for non-negative ``X`` such that the length is 32 bytes.\n- ``bool``: as in the ``uint8`` case, where ``1`` is used for ``true`` and ``0`` for ``false``\n- ``fixedx``: ``enc(X)`` is ``enc(X * 10**N)`` where ``X * 10**N`` is interpreted as a ``int256``.\n- ``fixed``: as in the ``fixed128x18`` case\n- ``ufixedx``: ``enc(X)`` is ``enc(X * 10**N)`` where ``X * 10**N`` is interpreted as a ``uint256``.\n- ``ufixed``: as in the ``ufixed128x18`` case\n- ``bytes``: ``enc(X)`` is the sequence of bytes in ``X`` padded with trailing zero-bytes to a length of 32 bytes.\n\nNote that for any ``X``, ``len(enc(X))`` is a multiple of 32.\n\nFunction Selector and Argument Encoding\n=======================================\n\nAll in all, a call to the function ``f`` with parameters ``a_1, ..., a_n`` is encoded as\n\n ``function_selector(f) enc((a_1, ..., a_n))``\n\nand the return values ``v_1, ..., v_k`` of ``f`` are encoded as\n\n ``enc((v_1, ..., v_k))``\n\ni.e. the values are combined into a tuple and encoded.\n\nExamples\n========\n\nGiven the contract:\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract Foo {\n function bar(bytes3[2] memory) public pure {}\n function baz(uint32 x, bool y) public pure returns (bool r) { r = x > 32 || y; }\n function sam(bytes memory, bool, uint[] memory) public pure {}\n }\n\n\nThus, for our ``Foo`` example, if we wanted to call ``bar`` with the argument ``[\"abc\", \"def\"]``, we would pass 68 bytes total, broken down into:\n\n- ``0xfce353f6``: the Method ID. This is derived from the signature ``bar(bytes3[2])``.\n- ``0x6162630000000000000000000000000000000000000000000000000000000000``: the first part of the first\n parameter, a ``bytes3`` value ``\"abc\"`` (left-aligned).\n- ``0x6465660000000000000000000000000000000000000000000000000000000000``: the second part of the first\n parameter, a ``bytes3`` value ``\"def\"`` (left-aligned).\n\nIn total:\n\n.. code-block:: none\n\n 0xfce353f661626300000000000000000000000000000000000000000000000000000000006465660000000000000000000000000000000000000000000000000000000000\n\nIf we wanted to call ``baz`` with the parameters ``69`` and\n``true``, we would pass 68 bytes total, which can be broken down into:\n\n- ``0xcdcd77c0``: the Method ID. This is derived as the first 4 bytes of the Keccak hash of\n the ASCII form of the signature ``baz(uint32,bool)``.\n- ``0x0000000000000000000000000000000000000000000000000000000000000045``: the first parameter,\n a uint32 value ``69`` padded to 32 bytes\n- ``0x0000000000000000000000000000000000000000000000000000000000000001``: the second parameter - boolean\n ``true``, padded to 32 bytes\n\nIn total:\n\n.. code-block:: none\n\n 0xcdcd77c000000000000000000000000000000000000000000000000000000000000000450000000000000000000000000000000000000000000000000000000000000001\n\nIt returns a single ``bool``. If, for example, it were to return ``false``, its output would be\nthe single byte array ``0x0000000000000000000000000000000000000000000000000000000000000000``, a single bool.\n\nIf we wanted to call ``sam`` with the arguments ``\"dave\"``, ``true`` and ``[1,2,3]``, we would\npass 292 bytes total, broken down into:\n\n- ``0xa5643bf2``: the Method ID. This is derived from the signature ``sam(bytes,bool,uint256[])``. Note that ``uint`` is replaced with its canonical representation ``uint256``.\n- ``0x0000000000000000000000000000000000000000000000000000000000000060``: the location of the data part of the first parameter (dynamic type), measured in bytes from the start of the arguments block. In this case, ``0x60``.\n- ``0x0000000000000000000000000000000000000000000000000000000000000001``: the second parameter: boolean true.\n- ``0x00000000000000000000000000000000000000000000000000000000000000a0``: the location of the data part of the third parameter (dynamic type), measured in bytes. In this case, ``0xa0``.\n- ``0x0000000000000000000000000000000000000000000000000000000000000004``: the data part of the first argument, it starts with the length of the byte array in elements, in this case, 4.\n- ``0x6461766500000000000000000000000000000000000000000000000000000000``: the contents of the first argument: the UTF-8 (equal to ASCII in this case) encoding of ``\"dave\"``, padded on the right to 32 bytes.\n- ``0x0000000000000000000000000000000000000000000000000000000000000003``: the data part of the third argument, it starts with the length of the array in elements, in this case, 3.\n- ``0x0000000000000000000000000000000000000000000000000000000000000001``: the first entry of the third parameter.\n- ``0x0000000000000000000000000000000000000000000000000000000000000002``: the second entry of the third parameter.\n- ``0x0000000000000000000000000000000000000000000000000000000000000003``: the third entry of the third parameter.\n\nIn total:\n\n.. code-block:: none\n\n 0xa5643bf20000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000464617665000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003\n\nUse of Dynamic Types\n====================\n\nA call to a function with the signature ``f(uint256,uint32[],bytes10,bytes)`` with values\n``(0x123, [0x456, 0x789], \"1234567890\", \"Hello, world!\")`` is encoded in the following way:\n\nWe take the first four bytes of ``keccak(\"f(uint256,uint32[],bytes10,bytes)\")``, i.e. ``0x8be65246``.\nThen we encode the head parts of all four arguments. For the static types ``uint256`` and ``bytes10``,\nthese are directly the values we want to pass, whereas for the dynamic types ``uint32[]`` and ``bytes``,\nwe use the offset in bytes to the start of their data area, measured from the start of the value\nencoding (i.e. not counting the first four bytes containing the hash of the function signature). These are:\n\n- ``0x0000000000000000000000000000000000000000000000000000000000000123`` (``0x123`` padded to 32 bytes)\n- ``0x0000000000000000000000000000000000000000000000000000000000000080`` (offset to start of data part of second parameter, 4*32 bytes, exactly the size of the head part)\n- ``0x3132333435363738393000000000000000000000000000000000000000000000`` (``\"1234567890\"`` padded to 32 bytes on the right)\n- ``0x00000000000000000000000000000000000000000000000000000000000000e0`` (offset to start of data part of fourth parameter = offset to start of data part of first dynamic parameter + size of data part of first dynamic parameter = 4\\*32 + 3\\*32 (see below))\n\nAfter this, the data part of the first dynamic argument, ``[0x456, 0x789]`` follows:\n\n- ``0x0000000000000000000000000000000000000000000000000000000000000002`` (number of elements of the array, 2)\n- ``0x0000000000000000000000000000000000000000000000000000000000000456`` (first element)\n- ``0x0000000000000000000000000000000000000000000000000000000000000789`` (second element)\n\nFinally, we encode the data part of the second dynamic argument, ``\"Hello, world!\"``:\n\n- ``0x000000000000000000000000000000000000000000000000000000000000000d`` (number of elements (bytes in this case): 13)\n- ``0x48656c6c6f2c20776f726c642100000000000000000000000000000000000000`` (``\"Hello, world!\"`` padded to 32 bytes on the right)\n\nAll together, the encoding is (newline after function selector and each 32-bytes for clarity):\n\n.. code-block:: none\n\n 0x8be65246\n 0000000000000000000000000000000000000000000000000000000000000123\n 0000000000000000000000000000000000000000000000000000000000000080\n 3132333435363738393000000000000000000000000000000000000000000000\n 00000000000000000000000000000000000000000000000000000000000000e0\n 0000000000000000000000000000000000000000000000000000000000000002\n 0000000000000000000000000000000000000000000000000000000000000456\n 0000000000000000000000000000000000000000000000000000000000000789\n 000000000000000000000000000000000000000000000000000000000000000d\n 48656c6c6f2c20776f726c642100000000000000000000000000000000000000\n\nLet us apply the same principle to encode the data for a function with a signature ``g(uint256[][],string[])``\nwith values ``([[1, 2], [3]], [\"one\", \"two\", \"three\"])`` but start from the most atomic parts of the encoding:\n\nFirst we encode the length and data of the first embedded dynamic array ``[1, 2]`` of the first root array ``[[1, 2], [3]]``:\n\n- ``0x0000000000000000000000000000000000000000000000000000000000000002`` (number of elements in the first array, 2; the elements themselves are ``1`` and ``2``)\n- ``0x0000000000000000000000000000000000000000000000000000000000000001`` (first element)\n- ``0x0000000000000000000000000000000000000000000000000000000000000002`` (second element)\n\nThen we encode the length and data of the second embedded dynamic array ``[3]`` of the first root array ``[[1, 2], [3]]``:\n\n- ``0x0000000000000000000000000000000000000000000000000000000000000001`` (number of elements in the second array, 1; the element is ``3``)\n- ``0x0000000000000000000000000000000000000000000000000000000000000003`` (first element)\n\nThen we need to find the offsets ``a`` and ``b`` for their respective dynamic arrays ``[1, 2]`` and ``[3]``.\nTo calculate the offsets we can take a look at the encoded data of the first root array ``[[1, 2], [3]]``\nenumerating each line in the encoding:\n\n.. code-block:: none\n\n 0 - a - offset of [1, 2]\n 1 - b - offset of [3]\n 2 - 0000000000000000000000000000000000000000000000000000000000000002 - count for [1, 2]\n 3 - 0000000000000000000000000000000000000000000000000000000000000001 - encoding of 1\n 4 - 0000000000000000000000000000000000000000000000000000000000000002 - encoding of 2\n 5 - 0000000000000000000000000000000000000000000000000000000000000001 - count for [3]\n 6 - 0000000000000000000000000000000000000000000000000000000000000003 - encoding of 3\n\nOffset ``a`` points to the start of the content of the array ``[1, 2]`` which is line\n2 (64 bytes); thus ``a = 0x0000000000000000000000000000000000000000000000000000000000000040``.\n\nOffset ``b`` points to the start of the content of the array ``[3]`` which is line 5 (160 bytes);\nthus ``b = 0x00000000000000000000000000000000000000000000000000000000000000a0``.\n\n\nThen we encode the embedded strings of the second root array:\n\n- ``0x0000000000000000000000000000000000000000000000000000000000000003`` (number of characters in word ``\"one\"``)\n- ``0x6f6e650000000000000000000000000000000000000000000000000000000000`` (utf8 representation of word ``\"one\"``)\n- ``0x0000000000000000000000000000000000000000000000000000000000000003`` (number of characters in word ``\"two\"``)\n- ``0x74776f0000000000000000000000000000000000000000000000000000000000`` (utf8 representation of word ``\"two\"``)\n- ``0x0000000000000000000000000000000000000000000000000000000000000005`` (number of characters in word ``\"three\"``)\n- ``0x7468726565000000000000000000000000000000000000000000000000000000`` (utf8 representation of word ``\"three\"``)\n\nIn parallel to the first root array, since strings are dynamic elements we need to find their offsets ``c``, ``d`` and ``e``:\n\n.. code-block:: none\n\n 0 - c - offset for \"one\"\n 1 - d - offset for \"two\"\n 2 - e - offset for \"three\"\n 3 - 0000000000000000000000000000000000000000000000000000000000000003 - count for \"one\"\n 4 - 6f6e650000000000000000000000000000000000000000000000000000000000 - encoding of \"one\"\n 5 - 0000000000000000000000000000000000000000000000000000000000000003 - count for \"two\"\n 6 - 74776f0000000000000000000000000000000000000000000000000000000000 - encoding of \"two\"\n 7 - 0000000000000000000000000000000000000000000000000000000000000005 - count for \"three\"\n 8 - 7468726565000000000000000000000000000000000000000000000000000000 - encoding of \"three\"\n\nOffset ``c`` points to the start of the content of the string ``\"one\"`` which is line 3 (96 bytes);\nthus ``c = 0x0000000000000000000000000000000000000000000000000000000000000060``.\n\nOffset ``d`` points to the start of the content of the string ``\"two\"`` which is line 5 (160 bytes);\nthus ``d = 0x00000000000000000000000000000000000000000000000000000000000000a0``.\n\nOffset ``e`` points to the start of the content of the string ``\"three\"`` which is line 7 (224 bytes);\nthus ``e = 0x00000000000000000000000000000000000000000000000000000000000000e0``.\n\n\nNote that the encodings of the embedded elements of the root arrays are not dependent on each other\nand have the same encodings for a function with a signature ``g(string[],uint256[][])``.\n\nThen we encode the length of the first root array:\n\n- ``0x0000000000000000000000000000000000000000000000000000000000000002`` (number of elements in the first root array, 2; the elements themselves are ``[1, 2]`` and ``[3]``)\n\nThen we encode the length of the second root array:\n\n- ``0x0000000000000000000000000000000000000000000000000000000000000003`` (number of strings in the second root array, 3; the strings themselves are ``\"one\"``, ``\"two\"`` and ``\"three\"``)\n\nFinally we find the offsets ``f`` and ``g`` for their respective root dynamic arrays ``[[1, 2], [3]]`` and\n``[\"one\", \"two\", \"three\"]``, and assemble parts in the correct order:\n\n.. code-block:: none\n\n 0x2289b18c - function signature\n 0 - f - offset of [[1, 2], [3]]\n 1 - g - offset of [\"one\", \"two\", \"three\"]\n 2 - 0000000000000000000000000000000000000000000000000000000000000002 - count for [[1, 2], [3]]\n 3 - 0000000000000000000000000000000000000000000000000000000000000040 - offset of [1, 2]\n 4 - 00000000000000000000000000000000000000000000000000000000000000a0 - offset of [3]\n 5 - 0000000000000000000000000000000000000000000000000000000000000002 - count for [1, 2]\n 6 - 0000000000000000000000000000000000000000000000000000000000000001 - encoding of 1\n 7 - 0000000000000000000000000000000000000000000000000000000000000002 - encoding of 2\n 8 - 0000000000000000000000000000000000000000000000000000000000000001 - count for [3]\n 9 - 0000000000000000000000000000000000000000000000000000000000000003 - encoding of 3\n 10 - 0000000000000000000000000000000000000000000000000000000000000003 - count for [\"one\", \"two\", \"three\"]\n 11 - 0000000000000000000000000000000000000000000000000000000000000060 - offset for \"one\"\n 12 - 00000000000000000000000000000000000000000000000000000000000000a0 - offset for \"two\"\n 13 - 00000000000000000000000000000000000000000000000000000000000000e0 - offset for \"three\"\n 14 - 0000000000000000000000000000000000000000000000000000000000000003 - count for \"one\"\n 15 - 6f6e650000000000000000000000000000000000000000000000000000000000 - encoding of \"one\"\n 16 - 0000000000000000000000000000000000000000000000000000000000000003 - count for \"two\"\n 17 - 74776f0000000000000000000000000000000000000000000000000000000000 - encoding of \"two\"\n 18 - 0000000000000000000000000000000000000000000000000000000000000005 - count for \"three\"\n 19 - 7468726565000000000000000000000000000000000000000000000000000000 - encoding of \"three\"\n\nOffset ``f`` points to the start of the content of the array ``[[1, 2], [3]]`` which is line 2 (64 bytes);\nthus ``f = 0x0000000000000000000000000000000000000000000000000000000000000040``.\n\nOffset ``g`` points to the start of the content of the array ``[\"one\", \"two\", \"three\"]`` which is line 10 (320 bytes);\nthus ``g = 0x0000000000000000000000000000000000000000000000000000000000000140``.\n\n.. _abi_events:\n\nEvents\n======\n\nEvents are an abstraction of the Ethereum logging/event-watching protocol. Log entries provide the contract's\naddress, a series of up to four topics and some arbitrary length binary data. Events leverage the existing function\nABI in order to interpret this (together with an interface spec) as a properly typed structure.\n\nGiven an event name and series of event parameters, we split them into two sub-series: those which are indexed and\nthose which are not.\nThose which are indexed, which may number up to 3 (for non-anonymous events) or 4 (for anonymous ones), are used\nalongside the Keccak hash of the event signature to form the topics of the log entry.\nThose which are not indexed form the byte array of the event.\n\nIn effect, a log entry using this ABI is described as:\n\n- ``address``: the address of the contract (intrinsically provided by Ethereum);\n- ``topics[0]``: ``keccak(EVENT_NAME+\"(\"+EVENT_ARGS.map(canonical_type_of).join(\",\")+\")\")`` (``canonical_type_of``\n is a function that simply returns the canonical type of a given argument, e.g. for ``uint indexed foo``, it would\n return ``uint256``). This value is only present in ``topics[0]`` if the event is not declared as ``anonymous``;\n- ``topics[n]``: ``abi_encode(EVENT_INDEXED_ARGS[n - 1])`` if the event is not declared as ``anonymous``\n or ``abi_encode(EVENT_INDEXED_ARGS[n])`` if it is (``EVENT_INDEXED_ARGS`` is the series of ``EVENT_ARGS`` that\n are indexed);\n- ``data``: ABI encoding of ``EVENT_NON_INDEXED_ARGS`` (``EVENT_NON_INDEXED_ARGS`` is the series of ``EVENT_ARGS``\n that are not indexed, ``abi_encode`` is the ABI encoding function used for returning a series of typed values\n from a function, as described above).\n\nFor all types of length at most 32 bytes, the ``EVENT_INDEXED_ARGS`` array contains\nthe value directly, padded or sign-extended (for signed integers) to 32 bytes, just as for regular ABI encoding.\nHowever, for all \"complex\" types or types of dynamic length, including all arrays, ``string``, ``bytes`` and structs,\n``EVENT_INDEXED_ARGS`` will contain the *Keccak hash* of a special in-place encoded value\n(see :ref:`indexed_event_encoding`), rather than the encoded value directly.\nThis allows applications to efficiently query for values of dynamic-length types\n(by setting the hash of the encoded value as the topic), but leaves applications unable\nto decode indexed values they have not queried for. For dynamic-length types,\napplication developers face a trade-off between fast search for predetermined values\n(if the argument is indexed) and legibility of arbitrary values (which requires that\nthe arguments not be indexed). Developers may overcome this tradeoff and achieve both\nefficient search and arbitrary legibility by defining events with two arguments — one\nindexed, one not — intended to hold the same value.\n\n.. _abi_errors:\n.. index:: error, selector; of an error\n\nErrors\n======\n\nIn case of a failure inside a contract, the contract can use a special opcode to abort execution and revert\nall state changes. In addition to these effects, descriptive data can be returned to the caller.\nThis descriptive data is the encoding of an error and its arguments in the same way as data for a function\ncall.\n\nAs an example, let us consider the following contract whose ``transfer`` function always\nreverts with a custom error of \"insufficient balance\":\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n\n contract TestToken {\n error InsufficientBalance(uint256 available, uint256 required);\n function transfer(address /*to*/, uint amount) public pure {\n revert InsufficientBalance(0, amount);\n }\n }\n\nThe return data would be encoded in the same way as the function call\n``InsufficientBalance(0, amount)`` to the function ``InsufficientBalance(uint256,uint256)``,\ni.e. ``0xcf479181``, ``uint256(0)``, ``uint256(amount)``.\n\nThe error selectors ``0x00000000`` and ``0xffffffff`` are reserved for future use.\n\n.. warning::\n Never trust error data.\n The error data by default bubbles up through the chain of external calls, which\n means that a contract may receive an error not defined in any of the contracts\n it calls directly.\n Furthermore, any contract can fake any error by returning data that matches\n an error signature, even if the error is not defined anywhere.\n\n.. _abi_json:\n\nJSON\n====\n\nThe JSON format for a contract's interface is given by an array of function, event and error descriptions.\nA function description is a JSON object with the fields:\n\n- ``type``: ``\"function\"``, ``\"constructor\"``, ``\"receive\"`` (the :ref:`\"receive Ether\" function `) or ``\"fallback\"`` (the :ref:`\"default\" function `);\n- ``name``: the name of the function;\n- ``inputs``: an array of objects, each of which contains:\n\n * ``name``: the name of the parameter.\n * ``type``: the canonical type of the parameter (more below).\n * ``components``: used for tuple types (more below).\n\n- ``outputs``: an array of objects similar to ``inputs``.\n- ``stateMutability``: a string with one of the following values: ``pure`` (:ref:`specified to not read\n blockchain state `), ``view`` (:ref:`specified to not modify the blockchain\n state `), ``nonpayable`` (function does not accept Ether - the default) and ``payable`` (function accepts Ether).\n\nConstructor, receive, and fallback never have ``name`` or ``outputs``. Receive and fallback do not have ``inputs`` either.\n\n.. note::\n Sending non-zero Ether to non-payable function will revert the transaction.\n\n.. note::\n The state mutability ``nonpayable`` is reflected in Solidity by not specifying\n a state mutability modifier at all.\n\nAn event description is a JSON object with fairly similar fields:\n\n- ``type``: always ``\"event\"``\n- ``name``: the name of the event.\n- ``inputs``: an array of objects, each of which contains:\n\n * ``name``: the name of the parameter.\n * ``type``: the canonical type of the parameter (more below).\n * ``components``: used for tuple types (more below).\n * ``indexed``: ``true`` if the field is part of the log's topics, ``false`` if it is one of the log's data segments.\n\n- ``anonymous``: ``true`` if the event was declared as ``anonymous``.\n\nErrors look as follows:\n\n- ``type``: always ``\"error\"``\n- ``name``: the name of the error.\n- ``inputs``: an array of objects, each of which contains:\n\n * ``name``: the name of the parameter.\n * ``type``: the canonical type of the parameter (more below).\n * ``components``: used for tuple types (more below).\n\n.. note::\n There can be multiple errors with the same name and even with identical signature\n in the JSON array; for example, if the errors originate from different\n files in the smart contract or are referenced from another smart contract.\n For the ABI, only the name of the error itself is relevant and not where it is\n defined.\n\n\nFor example,\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n\n\n contract Test {\n constructor() { b = hex\"12345678901234567890123456789012\"; }\n event Event(uint indexed a, bytes32 b);\n event Event2(uint indexed a, bytes32 b);\n error InsufficientBalance(uint256 available, uint256 required);\n function foo(uint a) public { emit Event(a, b); }\n bytes32 b;\n }\n\nwould result in the JSON:\n\n.. code-block:: json\n\n [{\n \"type\":\"error\",\n \"inputs\": [{\"name\":\"available\",\"type\":\"uint256\"},{\"name\":\"required\",\"type\":\"uint256\"}],\n \"name\":\"InsufficientBalance\"\n }, {\n \"type\":\"event\",\n \"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n \"name\":\"Event\"\n }, {\n \"type\":\"event\",\n \"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n \"name\":\"Event2\"\n }, {\n \"type\":\"function\",\n \"inputs\": [{\"name\":\"a\",\"type\":\"uint256\"}],\n \"name\":\"foo\",\n \"outputs\": []\n }]\n\nHandling tuple types\n--------------------\n\nDespite the fact that names are intentionally not part of the ABI encoding, they do make a lot of sense to be included\nin the JSON to enable displaying it to the end user. The structure is nested in the following way:\n\nAn object with members ``name``, ``type`` and potentially ``components`` describes a typed variable.\nThe canonical type is determined until a tuple type is reached and the string description up\nto that point is stored in ``type`` prefix with the word ``tuple``, i.e. it will be ``tuple`` followed by\na sequence of ``[]`` and ``[k]`` with\nintegers ``k``. The components of the tuple are then stored in the member ``components``,\nwhich is of an array type and has the same structure as the top-level object except that\n``indexed`` is not allowed there.\n\nAs an example, the code\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.5 <0.9.0;\n pragma abicoder v2;\n\n contract Test {\n struct S { uint a; uint[] b; T[] c; }\n struct T { uint x; uint y; }\n function f(S memory, T memory, uint) public pure {}\n function g() public pure returns (S memory, T memory, uint) {}\n }\n\nwould result in the JSON:\n\n.. code-block:: json\n\n [\n {\n \"name\": \"f\",\n \"type\": \"function\",\n \"inputs\": [\n {\n \"name\": \"s\",\n \"type\": \"tuple\",\n \"components\": [\n {\n \"name\": \"a\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"b\",\n \"type\": \"uint256[]\"\n },\n {\n \"name\": \"c\",\n \"type\": \"tuple[]\",\n \"components\": [\n {\n \"name\": \"x\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"y\",\n \"type\": \"uint256\"\n }\n ]\n }\n ]\n },\n {\n \"name\": \"t\",\n \"type\": \"tuple\",\n \"components\": [\n {\n \"name\": \"x\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"y\",\n \"type\": \"uint256\"\n }\n ]\n },\n {\n \"name\": \"a\",\n \"type\": \"uint256\"\n }\n ],\n \"outputs\": []\n }\n ]\n\n.. _abi_packed_mode:\n\nStrict Encoding Mode\n====================\n\nStrict encoding mode is the mode that leads to exactly the same encoding as defined in the formal specification above.\nThis means that offsets have to be as small as possible while still not creating overlaps in the data areas, and thus no gaps are\nallowed.\n\nUsually, ABI decoders are written in a straightforward way by just following offset pointers, but some decoders\nmight enforce strict mode. The Solidity ABI decoder currently does not enforce strict mode, but the encoder\nalways creates data in strict mode.\n\nNon-standard Packed Mode\n========================\n\nThrough ``abi.encodePacked()``, Solidity supports a non-standard packed mode where:\n\n- types shorter than 32 bytes are concatenated directly, without padding or sign extension\n- dynamic types are encoded in-place and without the length.\n- array elements are padded, but still encoded in-place\n\nFurthermore, structs as well as nested arrays are not supported.\n\nAs an example, the encoding of ``int16(-1), bytes1(0x42), uint16(0x03), string(\"Hello, world!\")`` results in:\n\n.. code-block:: none\n\n 0xffff42000348656c6c6f2c20776f726c6421\n ^^^^ int16(-1)\n ^^ bytes1(0x42)\n ^^^^ uint16(0x03)\n ^^^^^^^^^^^^^^^^^^^^^^^^^^ string(\"Hello, world!\") without a length field\n\nMore specifically:\n\n- During the encoding, everything is encoded in-place. This means that there is\n no distinction between head and tail, as in the ABI encoding, and the length\n of an array is not encoded.\n- The direct arguments of ``abi.encodePacked`` are encoded without padding,\n as long as they are not arrays (or ``string`` or ``bytes``).\n- The encoding of an array is the concatenation of the\n encoding of its elements **with** padding.\n- Dynamically-sized types like ``string``, ``bytes`` or ``uint[]`` are encoded\n without their length field.\n- The encoding of ``string`` or ``bytes`` does not apply padding at the end,\n unless it is part of an array or struct (then it is padded to a multiple of\n 32 bytes).\n\nIn general, the encoding is ambiguous as soon as there are two dynamically-sized elements,\nbecause of the missing length field.\n\nIf padding is needed, explicit type conversions can be used: ``abi.encodePacked(uint16(0x12)) == hex\"0012\"``.\n\nSince packed encoding is not used when calling functions, there is no special support\nfor prepending a function selector. Since the encoding is ambiguous, there is no decoding function.\n\n.. warning::\n\n If you use ``keccak256(abi.encodePacked(a, b))`` and both ``a`` and ``b`` are dynamic types,\n it is easy to craft collisions in the hash value by moving parts of ``a`` into ``b`` and\n vice-versa. More specifically, ``abi.encodePacked(\"a\", \"bc\") == abi.encodePacked(\"ab\", \"c\")``.\n If you use ``abi.encodePacked`` for signatures, authentication or data integrity, make\n sure to always use the same types and check that at most one of them is dynamic.\n Unless there is a compelling reason, ``abi.encode`` should be preferred.\n\n\n.. _indexed_event_encoding:\n\nEncoding of Indexed Event Parameters\n====================================\n\nIndexed event parameters that are not value types, i.e. arrays and structs are not\nstored directly but instead a Keccak-256 hash of an encoding is stored. This encoding\nis defined as follows:\n\n- the encoding of a ``bytes`` and ``string`` value is just the string contents\n without any padding or length prefix.\n- the encoding of a struct is the concatenation of the encoding of its members,\n always padded to a multiple of 32 bytes (even ``bytes`` and ``string``).\n- the encoding of an array (both dynamically- and statically-sized) is\n the concatenation of the encoding of its elements, always padded to a multiple\n of 32 bytes (even ``bytes`` and ``string``) and without any length prefix\n\nIn the above, as usual, a negative number is padded by sign extension and not zero padded.\n``bytesNN`` types are padded on the right while ``uintNN`` / ``intNN`` are padded on the left.\n\n.. warning::\n\n The encoding of a struct is ambiguous if it contains more than one dynamically-sized\n array. Because of that, always re-check the event data and do not rely on the search result\n based on the indexed parameters alone.\n" }, { "path": "docs/analysing-compilation-output.rst", "content": ".. index:: analyse, asm\n\n#############################\nAnalysing the Compiler Output\n#############################\n\nIt is often useful to look at the assembly code generated by the compiler. The generated binary,\ni.e., the output of ``solc --bin contract.sol``, is generally difficult to read. It is recommended\nto use the flag ``--asm`` to analyse the assembly output. Even for large contracts, looking at a\nvisual diff of the assembly before and after a change is often very enlightening.\n\nConsider the following contract (named, say ``contract.sol``):\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n contract C {\n function one() public pure returns (uint) {\n return 1;\n }\n }\n\nThe following would be the output of ``solc --asm contract.sol``\n\n.. code-block:: none\n\n ======= contract.sol:C =======\n EVM assembly:\n /* \"contract.sol\":0:86 contract C {... */\n mstore(0x40, 0x80)\n callvalue\n dup1\n iszero\n tag_1\n jumpi\n 0x00\n dup1\n revert\n tag_1:\n pop\n dataSize(sub_0)\n dup1\n dataOffset(sub_0)\n 0x00\n codecopy\n 0x00\n return\n stop\n\n sub_0: assembly {\n /* \"contract.sol\":0:86 contract C {... */\n mstore(0x40, 0x80)\n callvalue\n dup1\n iszero\n tag_1\n jumpi\n 0x00\n dup1\n revert\n tag_1:\n pop\n jumpi(tag_2, lt(calldatasize, 0x04))\n shr(0xe0, calldataload(0x00))\n dup1\n 0x901717d1\n eq\n tag_3\n jumpi\n tag_2:\n 0x00\n dup1\n revert\n /* \"contract.sol\":17:84 function one() public pure returns (uint) {... */\n tag_3:\n tag_4\n tag_5\n jump\t// in\n tag_4:\n mload(0x40)\n tag_6\n swap2\n swap1\n tag_7\n jump\t// in\n tag_6:\n mload(0x40)\n dup1\n swap2\n sub\n swap1\n return\n tag_5:\n /* \"contract.sol\":53:57 uint */\n 0x00\n /* \"contract.sol\":76:77 1 */\n 0x01\n /* \"contract.sol\":69:77 return 1 */\n swap1\n pop\n /* \"contract.sol\":17:84 function one() public pure returns (uint) {... */\n swap1\n jump\t// out\n /* \"#utility.yul\":7:125 */\n tag_10:\n /* \"#utility.yul\":94:118 */\n tag_12\n /* \"#utility.yul\":112:117 */\n dup2\n /* \"#utility.yul\":94:118 */\n tag_13\n jump\t// in\n tag_12:\n /* \"#utility.yul\":89:92 */\n dup3\n /* \"#utility.yul\":82:119 */\n mstore\n /* \"#utility.yul\":72:125 */\n pop\n pop\n jump\t// out\n /* \"#utility.yul\":131:353 */\n tag_7:\n 0x00\n /* \"#utility.yul\":262:264 */\n 0x20\n /* \"#utility.yul\":251:260 */\n dup3\n /* \"#utility.yul\":247:265 */\n add\n /* \"#utility.yul\":239:265 */\n swap1\n pop\n /* \"#utility.yul\":275:346 */\n tag_15\n /* \"#utility.yul\":343:344 */\n 0x00\n /* \"#utility.yul\":332:341 */\n dup4\n /* \"#utility.yul\":328:345 */\n add\n /* \"#utility.yul\":319:325 */\n dup5\n /* \"#utility.yul\":275:346 */\n tag_10\n jump\t// in\n tag_15:\n /* \"#utility.yul\":229:353 */\n swap3\n swap2\n pop\n pop\n jump\t// out\n /* \"#utility.yul\":359:436 */\n tag_13:\n 0x00\n /* \"#utility.yul\":425:430 */\n dup2\n /* \"#utility.yul\":414:430 */\n swap1\n pop\n /* \"#utility.yul\":404:436 */\n swap2\n swap1\n pop\n jump\t// out\n\n auxdata: 0xa2646970667358221220a5874f19737ddd4c5d77ace1619e5160c67b3d4bedac75fce908fed32d98899864736f6c637827302e382e342d646576656c6f702e323032312e332e33302b636f6d6d69742e65613065363933380058\n }\n\nAlternatively, the above output can also be obtained from `Remix `_,\nunder the option \"Compilation Details\" after compiling a contract.\n\nNotice that the ``asm`` output starts with the creation / constructor code. The deploy code is\nprovided as part of the sub object (in the above example, it is part of the sub-object ``sub_0``).\nThe ``auxdata`` field corresponds to the contract :ref:`metadata\n`. The comments in the assembly output point to the\nsource location. Note that ``#utility.yul`` is an internally generated file of utility functions\nthat can be obtained using the flags ``--combined-json\ngenerated-sources,generated-sources-runtime``.\n\nSimilarly, the optimized assembly can be obtained with the command: ``solc --optimize --asm\ncontract.sol``. Often times, it is interesting to see if two different sources in Solidity result in\nthe same optimized code. For example, to see if the expressions ``(a * b) / c``, ``a * b / c``\ngenerates the same bytecode. This can be easily done by taking a ``diff`` of the corresponding\nassembly output, after potentially stripping comments that reference the source locations.\n\n.. note::\n\n The ``--asm`` output is not designed to be machine readable. Therefore, there may be breaking\n changes on the output between minor versions of solc.\n" }, { "path": "docs/assembly.rst", "content": ".. _inline-assembly:\n\n###############\nInline Assembly\n###############\n\n.. index:: ! assembly, ! asm, ! evmasm\n\n\nYou can interleave Solidity statements with inline assembly in a language close\nto the one of the Ethereum Virtual Machine. This gives you more fine-grained control,\nwhich is especially useful when you are enhancing the language by writing libraries or\noptimizing gas usage.\n\nThe language used for inline assembly in Solidity is called :ref:`Yul `\nand it is documented in its own section. This section will only cover\nhow the inline assembly code can interface with the surrounding Solidity code.\n\n\n.. warning::\n Inline assembly is a way to access the Ethereum Virtual Machine\n at a low level. This bypasses several important safety\n features and checks of Solidity. You should only use it for\n tasks that need it, and only if you are confident with using it.\n\n\nAn inline assembly block is marked by ``assembly { ... }``, where the code inside\nthe curly braces is code in the :ref:`Yul ` language.\n\nThe inline assembly code can access local Solidity variables as explained below.\n\nDifferent inline assembly blocks share no namespace, i.e. it is not possible\nto call a Yul function or access a Yul variable defined in a different inline assembly block.\n\nExample\n-------\n\nThe following example provides library code to access the code of another contract and\nload it into a ``bytes`` variable. This is possible with \"plain Solidity\" too, by using\n``
.code``. But the point here is that reusable assembly libraries can enhance the\nSolidity language without a compiler change.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n library GetCode {\n function at(address addr) public view returns (bytes memory code) {\n assembly {\n // retrieve the size of the code, this needs assembly\n let size := extcodesize(addr)\n // allocate output byte array - this could also be done without assembly\n // by using code = new bytes(size)\n code := mload(0x40)\n // new \"memory end\" including padding\n mstore(0x40, add(code, and(add(add(size, 0x20), 0x1f), not(0x1f))))\n // store length in memory\n mstore(code, size)\n // actually retrieve the code, this needs assembly\n extcodecopy(addr, add(code, 0x20), 0, size)\n }\n }\n }\n\nInline assembly is also beneficial in cases where the optimizer fails to produce\nefficient code, for example:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n\n library VectorSum {\n // This function is less efficient because the optimizer currently fails to\n // remove the bounds checks in array access.\n function sumSolidity(uint[] memory data) public pure returns (uint sum) {\n for (uint i = 0; i < data.length; ++i)\n sum += data[i];\n }\n\n // We know that we only access the array in bounds, so we can avoid the check.\n // 0x20 needs to be added to an array because the first slot contains the\n // array length.\n function sumAsm(uint[] memory data) public pure returns (uint sum) {\n for (uint i = 0; i < data.length; ++i) {\n assembly {\n sum := add(sum, mload(add(add(data, 0x20), mul(i, 0x20))))\n }\n }\n }\n\n // Same as above, but accomplish the entire code within inline assembly.\n function sumPureAsm(uint[] memory data) public pure returns (uint sum) {\n assembly {\n // Load the length (first 32 bytes)\n let len := mload(data)\n\n // Skip over the length field.\n //\n // Keep temporary variable so it can be incremented in place.\n //\n // NOTE: incrementing data would result in an unusable\n // data variable after this assembly block\n let dataElementLocation := add(data, 0x20)\n\n // Iterate until the bound is not met.\n for\n { let end := add(dataElementLocation, mul(len, 0x20)) }\n lt(dataElementLocation, end)\n { dataElementLocation := add(dataElementLocation, 0x20) }\n {\n sum := add(sum, mload(dataElementLocation))\n }\n }\n }\n }\n\n.. index:: selector; of a function\n\nAccess to External Variables, Functions and Libraries\n-----------------------------------------------------\n\nYou can access Solidity variables and other identifiers by using their name.\n\nLocal variables of value type are directly usable in inline assembly.\nThey can both be read and assigned to.\n\nLocal variables that refer to memory evaluate to the address of the variable in memory, not the value itself.\nSuch variables can also be assigned to, but note that an assignment will only change the pointer and not the data\nand that it is your responsibility to respect Solidity's memory management.\nSee :ref:`Conventions in Solidity `.\n\nSimilarly, local variables that refer to statically-sized calldata arrays or calldata structs\nevaluate to the address of the variable in calldata, not the value itself.\nThe variable can also be assigned a new offset, but note that no validation is performed to ensure that\nthe variable will not point beyond ``calldatasize()``.\n\nFor external function pointers the address and the function selector can be\naccessed using ``x.address`` and ``x.selector``.\nThe selector consists of four right-aligned bytes.\nBoth values can be assigned to. For example:\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.10 <0.9.0;\n\n contract C {\n // Assigns a new selector and address to the return variable @fun\n function combineToFunctionPointer(address newAddress, uint newSelector) public pure returns (function() external fun) {\n assembly {\n fun.selector := newSelector\n fun.address := newAddress\n }\n }\n }\n\nFor dynamic calldata arrays, you can access\ntheir calldata offset (in bytes) and length (number of elements) using ``x.offset`` and ``x.length``.\nBoth expressions can also be assigned to, but as for the static case, no validation will be performed\nto ensure that the resulting data area is within the bounds of ``calldatasize()``.\n\nFor local storage variables or state variables (including transient storage) a single Yul identifier\nis not sufficient, since they do not necessarily occupy a single full storage slot.\nTherefore, their \"address\" is composed of a slot and a byte-offset\ninside that slot. To retrieve the slot pointed to by the variable ``x``, you\nuse ``x.slot``, and to retrieve the byte-offset you use ``x.offset``.\nUsing ``x`` itself will result in an error.\n\nYou can also assign to the ``.slot`` part of a local storage variable pointer.\nFor these (structs, arrays or mappings), the ``.offset`` part is always zero.\nIt is not possible to assign to the ``.slot`` or ``.offset`` part of a state variable,\nthough.\n\nLocal Solidity variables are available for assignments, for example:\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.28 <0.9.0;\n\n // This will report a warning\n contract C {\n bool transient a;\n uint b;\n function f(uint x) public returns (uint r) {\n assembly {\n // We ignore the storage slot offset, we know it is zero\n // in this special case.\n r := mul(x, sload(b.slot))\n tstore(a.slot, true)\n }\n }\n }\n\n.. warning::\n If you access variables of a type that spans less than 256 bits\n (for example ``uint64``, ``address``, or ``bytes16``),\n you cannot make any assumptions about bits not part of the\n encoding of the type. Especially, do not assume them to be zero.\n To be safe, always clear the data properly before you use it\n in a context where this is important:\n ``uint32 x = f(); assembly { x := and(x, 0xffffffff) /* now use x */ }``\n To clean signed types, you can use the ``signextend`` opcode:\n ``assembly { signextend(, x) }``\n\n\nSince Solidity 0.6.0, the name of an inline assembly variable may not\nshadow any declaration visible in the scope of the inline assembly block\n(including variable, contract and function declarations).\n\nSince Solidity 0.7.0, variables and functions declared inside the\ninline assembly block may not contain ``.``, but using ``.`` is\nvalid to access Solidity variables from outside the inline assembly block.\nHowever, it is still valid to use dots if you use Solidity in Yul-only mode.\n\nThings to Avoid\n---------------\n\nInline assembly might have a quite high-level look, but it actually is extremely\nlow-level. Function calls, loops, ifs and switches are converted by simple\nrewriting rules and after that, the only thing the assembler does for you is re-arranging\nfunctional-style opcodes, counting stack height for\nvariable access and removing stack slots for assembly-local variables when the end\nof their block is reached.\n\n.. _conventions-in-solidity:\n\nConventions in Solidity\n-----------------------\n\n.. _assembly-typed-variables:\n\nValues of Typed Variables\n=========================\n\nIn contrast to EVM assembly, Solidity has types which are narrower than 256 bits,\ne.g. ``uint24``. For efficiency, most arithmetic operations ignore the fact that\ntypes can be shorter than 256\nbits, and the higher-order bits are cleaned when necessary,\ni.e., shortly before they are written to memory or before comparisons are performed.\nThis means that if you access such a variable\nfrom within inline assembly, you might have to manually clean the higher-order bits\nfirst.\n\n.. _assembly-memory-management:\n\nMemory Management\n=================\n\nSolidity manages memory in the following way. There is a \"free memory pointer\"\nat position ``0x40`` in memory. If you want to allocate memory, use the memory\nstarting from where this pointer points at and update it.\nThere is no guarantee that the memory has not been used before and thus\nyou cannot assume that its contents are zero bytes.\nThere is no built-in mechanism to release or free allocated memory.\nSolidity does not guarantee and does not require that the values in memory\nare placed at positions aligned to a multiple of any value.\nHere is an assembly snippet you can use for allocating memory that follows the process outlined above:\n\n.. code-block:: yul\n\n function allocate(length) -> pos {\n pos := mload(0x40)\n mstore(0x40, add(pos, length))\n }\n\nThe first 64 bytes of memory can be used as \"scratch space\" for short-term\nallocation. The 32 bytes after the free memory pointer (i.e., starting at ``0x60``)\nare meant to be zero permanently and is used as the initial value for\nempty dynamic memory arrays.\nThis means that the allocatable memory starts at ``0x80``, which is the initial value\nof the free memory pointer.\n\nElements in memory arrays in Solidity always occupy multiples of 32 bytes (this is\neven true for ``bytes1[]``, but not for ``bytes`` and ``string``). Multi-dimensional memory\narrays are pointers to memory arrays. The length of a dynamic array is stored at the\nfirst slot of the array and followed by the array elements.\n\n.. warning::\n Statically-sized memory arrays do not have a length field, but it might be added later\n to allow better convertibility between statically and dynamically-sized arrays; so,\n do not rely on this.\n\nMemory Safety\n=============\n\nWithout the use of inline assembly, the compiler can rely on memory to remain in a well-defined\nstate at all times. This is especially relevant for :ref:`the new code generation pipeline via Yul IR `:\nthis code generation path can move local variables from stack to memory to avoid stack-too-deep errors and\nperform additional memory optimizations, if it can rely on certain assumptions about memory use.\n\nWhile we recommend to always respect Solidity's memory model, inline assembly allows you to use memory\nin an incompatible way. Therefore, moving stack variables to memory and additional memory optimizations are,\nby default, globally disabled in the presence of any inline assembly block that contains a memory operation\nor assigns to Solidity variables in memory.\n\nHowever, you can specifically annotate an assembly block to indicate that it in fact respects Solidity's memory\nmodel as follows:\n\n.. code-block:: solidity\n\n assembly (\"memory-safe\") {\n ...\n }\n\nIn particular, a memory-safe assembly block may only access the following memory ranges:\n\n- Memory allocated by yourself using a mechanism like the ``allocate`` function described above.\n- Memory allocated by Solidity, e.g. memory within the bounds of a memory array you reference.\n- The scratch space between memory offset 0 and 64 mentioned above.\n- Temporary memory that is located *after* the value of the free memory pointer at the beginning of the assembly block,\n i.e. memory that is \"allocated\" at the free memory pointer without updating the free memory pointer.\n\nFurthermore, if the assembly block assigns to Solidity variables in memory, you need to assure that accesses to\nthe Solidity variables only access these memory ranges.\n\nSince this is mainly about the optimizer, these restrictions still need to be followed, even if the assembly block\nreverts or terminates. As an example, the following assembly snippet is not memory safe, because the value of\n``returndatasize()`` may exceed the 64 byte scratch space:\n\n.. code-block:: solidity\n\n assembly {\n returndatacopy(0, 0, returndatasize())\n revert(0, returndatasize())\n }\n\nOn the other hand, the following code *is* memory safe, because memory beyond the location pointed to by the\nfree memory pointer can safely be used as temporary scratch space:\n\n.. code-block:: solidity\n\n assembly (\"memory-safe\") {\n let p := mload(0x40)\n returndatacopy(p, 0, returndatasize())\n revert(p, returndatasize())\n }\n\nNote that you do not need to update the free memory pointer if there is no following allocation,\nbut you can only use memory starting from the current offset given by the free memory pointer.\n\nIf the memory operations use a length of zero, it is also fine to just use any offset (not only if it falls into the scratch space):\n\n.. code-block:: solidity\n\n assembly (\"memory-safe\") {\n revert(0, 0)\n }\n\nNote that not only memory operations in inline assembly itself can be memory-unsafe, but also assignments to\nSolidity variables of reference type in memory. For example the following is not memory-safe:\n\n.. code-block:: solidity\n\n bytes memory x;\n assembly {\n x := 0x40\n }\n x[0x20] = 0x42;\n\nInline assembly that neither involves any operations that access memory nor assigns to any Solidity variables\nin memory is automatically considered memory-safe and does not need to be annotated.\n\n.. warning::\n It is your responsibility to make sure that the assembly actually satisfies the memory model. If you annotate\n an assembly block as memory-safe, but violate one of the memory assumptions, this **will** lead to incorrect and\n undefined behavior that cannot easily be discovered by testing.\n\nIn case you are developing a library that is meant to be compatible across multiple versions\nof Solidity, you can use a special comment to annotate an assembly block as memory-safe:\n\n.. code-block:: solidity\n\n /// @solidity memory-safe-assembly\n assembly {\n ...\n }\n\n.. warning::\n The ``memory-safe-assembly`` special comment is deprecated and scheduled for removal.\n In new code targeting recent compilers, use the assembly block annotation.\n\nAdvanced Safe Use of Memory\n---------------------------\n\nBeyond the strict definition of memory-safety given above, there are cases in which you may want to use more than 64 bytes\nof scratch space starting at memory offset ``0``. If you are careful, it can be admissible to use memory up to (and not\nincluding) offset ``0x80`` and still safely declare the assembly block as ``memory-safe``.\nThis is admissible under either of the following conditions:\n\n- By the end of the assembly block, the free memory pointer at offset ``0x40`` is restored to a sane value (i.e. it is either\n restored to its original value or an increment of it due to a manual memory allocation), and the memory word at offset ``0x60``\n is restored to a value of zero.\n\n- The assembly block terminates, i.e. execution can never return to high-level Solidity code. This is the case, for example,\n if your assembly block unconditionally ends in calling the ``revert`` opcode.\n\nFurthermore, you need to be aware that the default-value of dynamic arrays in Solidity point to memory offset ``0x60``, so\nfor the duration of temporarily changing the value at memory offset ``0x60``, you can no longer rely on getting accurate\nlength values when reading dynamic arrays, until you restore the zero value at ``0x60``. To be more precise, we only guarantee\nsafety when overwriting the zero pointer, if the remainder of the assembly snippet does not interact with the memory of\nhigh-level Solidity objects (including by reading from offsets previously stored in variables).\n" }, { "path": "docs/brand-guide.rst", "content": "####################\nSolidity Brand Guide\n####################\n\nThis brand guide features information on Solidity's brand policy and\nlogo usage guidelines.\n\nThe Solidity Brand\n==================\n\nThe Solidity programming language is an open-source, community project\ngoverned by a core team. The core team is sponsored by the `Ethereum\nFoundation `_.\n\nThis document aims to provide information about how to best use the\nSolidity brand name and logo.\n\nWe encourage you to read this document carefully before using the\nbrand name or the logo. Your cooperation is highly appreciated!\n\nSolidity Brand Name\n===================\n\n\"Solidity\" should be used to refer to the Solidity programming language\nsolely.\n\nPlease do not use \"Solidity\":\n\n- To refer to any other programming language.\n\n- In a way that is misleading or may imply association of unrelated\n modules, tools, documentation, or other resources with the Solidity\n programming language.\n\n- In ways that confuse the community as to whether the Solidity\n programming language is open-source and free to use.\n\nSolidity Logo License\n=====================\n\n.. image:: https://i.creativecommons.org/l/by/4.0/88x31.png\n :width: 88\n :alt: Creative Commons License\n\nThe Solidity logo is distributed and licensed under a `Creative Commons\nAttribution 4.0 International License `_.\n\nThis is the most permissive Creative Commons license and allows reuse\nand modifications for any purpose.\n\nYou are free to:\n\n- **Share** — Copy and redistribute the material in any medium or format.\n\n- **Adapt** — Remix, transform, and build upon the material for any\n purpose, even commercially.\n\nUnder the following terms:\n\n- **Attribution** — You must give appropriate credit, provide a link to\n the license, and indicate if changes were made. You may do so in any\n reasonable manner, but not in any way that suggests that the Solidity\n core team endorses you or your use.\n\nWhen using the Solidity logo, please respect the Solidity logo guidelines.\n\nSolidity Logo Guidelines\n========================\n\n.. image:: solidity_logo.svg\n :width: 256\n\n*(Right click on the logo to download it.)*\n\nPlease do not:\n\n- Change the ratio of the logo (do not stretch it or cut it).\n\n- Change the colors of the logo, unless it is absolutely necessary.\n\nCredits\n=======\n\nThis document was, in parts, derived from the `Python Software\nFoundation Trademark Usage Policy `_\nand the `Rust Media Guide `_.\n" }, { "path": "docs/bugs.json", "content": "[\n {\n \"uid\": \"SOL-2026-1\",\n \"name\": \"TransientStorageClearingHelperCollision\",\n \"summary\": \"Clearing both storage and transient storage variables in the same contract may result in only one of these locations being cleared.\",\n \"description\": \"The IR-based code generator provides a set of Yul helper functions for basic operations, such as clearing, copying, encoding or type conversions. Not all functions are used by every contract. The codegen appends them to the generated sources individually, only when an operation that would invoke one of them is encountered. Utility functions are often specialized for different types and locations. Since Yul does not support generic functions, specialization is done by generating multiple versions of the same function, with the information distinguishing the variants embedded in their names. However, if not all the necessary bits of distinguishing information are properly accounted for, two helpers may end up with the same name, causing a collision. In this situation the codegen includes only one of them, with calls to both variants invoking it. This happened with the ``set_to_zero`` helper used when an area of transient or persistent storage needs to be cleared. The helper name was missing the location information, which resulted in a collision between the persistent and transient storage variants for the same type. This meant that contracts clearing both locations would actually clear only one, leaving the other untouched. Which location ended up being cleared depended on the order in which the code generator processed the input. The necessary condition to trigger the bug was the use of ``delete`` operator on a transient storage variable. This was due to value types being the only types supported in transient storage and ``delete`` being the only operation invoking the helper allowed on such types. The other necessary condition was clearing of persistent storage and in this case the range of affected operations was wider: operator ``delete``, array ``pop()`` or assignment that resulted in a longer array being overwritten with a shorter one. The cleared variable itself also did not necessarily have to be of the same type. It was enough that a matching value type was nested in it. It also did not always have to be the exact same value type - clearing operations on reference types are usually performed at slot granularity, treating every slot as ``uint256`` rather than clearing every value packed into it individually. To trigger the bug both operations had to be present within the same piece of bytecode. Independent contracts, not related through inheritance, would not affect each other this way. The presence of one operation only in creation code and the other only in deployed code would not trigger the bug either.\",\n \"link\": \"https://blog.soliditylang.org/2026/02/18/transient-storage-clearing-helper-collision-bug/\",\n \"introduced\": \"0.8.28\",\n \"fixed\": \"0.8.34\",\n \"severity\": \"high\",\n \"conditions\": {\n \"viaIR\": true,\n \"evmVersion\": \">=cancun\"\n }\n },\n {\n \"uid\": \"SOL-2025-1\",\n \"name\": \"LostStorageArrayWriteOnSlotOverflow\",\n \"summary\": \"Operations that involve clearing or copying from arrays that straddle the end of storage could result in silent data retention.\",\n \"description\": \"Solidity makes it possible to define variables that extend past the last (2**256-th) slot of storage, which results in wrap-around back to slot zero. Since EVM uses 256-bit integer arithmetic, most operations on such variables just work. The only situation which requires special attention is iteration against absolute slot addresses: the invariant that the last slot belonging to a variable has the highest address does not hold. When implemented incorrectly, a loop over an array will immediately terminate if the container spans the end of storage - due to the initial position already being greater than the end position. This affected storage array clearing loops generated by both evmasm and IR pipelines. Additionally, (only in the evmasm pipeline) copying operations whose source was an array straddling the end of storage were also affected. At the language level, the buggy code would be generated for array assignment, array initialization, delete operator, .pop() and .push(). Note that a clearing loop is inserted by the compiler not only for invocations of the delete operator, but also to zero storage when overwriting a longer array with a shorter one, popping an element or even pushing an empty element to a dynamic array. Since clearing is a separate loop, it is possible for the bug to only affect it and not the copy operation it follows (which is always the case in the IR pipeline). The bug is extremely unlikely to be triggered accidentally due to the probabilistic impossibility of a short dynamic array being allocated right at the storage boundary. On the other hand, scenarios in which a user may place a static array there intentionally do not seem realistic and are limited to unusual layouts, in which a contract does not place any storage variables at slot zero (otherwise they would overlap the array).\",\n \"link\": \"https://blog.soliditylang.org/2025/12/18/lost-storage-array-write-on-slot-overflow-bug/\",\n \"introduced\": \"0.1.0\",\n \"fixed\": \"0.8.32\",\n \"severity\": \"low\"\n },\n {\n \"uid\": \"SOL-2023-3\",\n \"name\": \"VerbatimInvalidDeduplication\",\n \"summary\": \"All ``verbatim`` blocks are considered identical by deduplicator and can incorrectly be unified when surrounded by identical opcodes.\",\n \"description\": \"The block deduplicator is a step of the opcode-based optimizer which identifies equivalent assembly blocks and merges them into a single one. However, when blocks contained ``verbatim``, their comparison was performed incorrectly, leading to the collapse of assembly blocks which are identical except for the contents of the ``verbatim`` items. Since ``verbatim`` is only available in Yul, compilation of Solidity sources is not affected.\",\n \"link\": \"https://blog.soliditylang.org/2023/11/08/verbatim-invalid-deduplication-bug/\",\n \"introduced\": \"0.8.5\",\n \"fixed\": \"0.8.23\",\n \"severity\": \"low\"\n },\n {\n \"uid\": \"SOL-2023-2\",\n \"name\": \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"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.\",\n \"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.\",\n \"link\": \"https://blog.soliditylang.org/2023/07/19/full-inliner-non-expression-split-argument-evaluation-order-bug/\",\n \"introduced\": \"0.6.7\",\n \"fixed\": \"0.8.21\",\n \"severity\": \"low\",\n \"conditions\": {\n \"yulOptimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2023-1\",\n \"name\": \"MissingSideEffectsOnSelectorAccess\",\n \"summary\": \"Accessing the ``.selector`` member on complex expressions leaves the expression unevaluated in the legacy code generation.\",\n \"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.\",\n \"link\": \"https://blog.soliditylang.org/2023/07/19/missing-side-effects-on-selector-access-bug/\",\n \"introduced\": \"0.6.2\",\n \"fixed\": \"0.8.21\",\n \"severity\": \"low\",\n \"conditions\": {\n \"viaIR\": false\n }\n },\n {\n \"uid\": \"SOL-2022-7\",\n \"name\": \"StorageWriteRemovalBeforeConditionalTermination\",\n \"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.\",\n \"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.\",\n \"link\": \"https://blog.soliditylang.org/2022/09/08/storage-write-removal-before-conditional-termination/\",\n \"introduced\": \"0.8.13\",\n \"fixed\": \"0.8.17\",\n \"severity\": \"medium/high\",\n \"conditions\": {\n \"yulOptimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2022-6\",\n \"name\": \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"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.\",\n \"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.\",\n \"link\": \"https://blog.soliditylang.org/2022/08/08/calldata-tuple-reencoding-head-overflow-bug/\",\n \"introduced\": \"0.5.8\",\n \"fixed\": \"0.8.16\",\n \"severity\": \"medium\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n }\n },\n {\n \"uid\": \"SOL-2022-5\",\n \"name\": \"DirtyBytesArrayToStorage\",\n \"summary\": \"Copying ``bytes`` arrays from memory or calldata to storage may result in dirty storage values.\",\n \"description\": \"Copying ``bytes`` arrays from memory or calldata to storage is done in chunks of 32 bytes even if the length is not a multiple of 32. Thereby, extra bytes past the end of the array may be copied from calldata or memory to storage. These dirty bytes may then become observable after a ``.push()`` without arguments to the bytes array in storage, i.e. such a push will not result in a zero value at the end of the array as expected. This bug only affects the legacy code generation pipeline, the new code generation pipeline via IR is not affected.\",\n \"link\": \"https://blog.soliditylang.org/2022/06/15/dirty-bytes-array-to-storage-bug/\",\n \"introduced\": \"0.0.1\",\n \"fixed\": \"0.8.15\",\n \"severity\": \"low\"\n },\n {\n \"uid\": \"SOL-2022-4\",\n \"name\": \"InlineAssemblyMemorySideEffects\",\n \"summary\": \"The Yul optimizer may incorrectly remove memory writes from inline assembly blocks, that do not access solidity variables.\",\n \"description\": \"The Yul optimizer considers all memory writes in the outermost Yul block that are never read from as unused and removes them. This is valid when that Yul block is the entire Yul program, which is always the case for the Yul code generated by the new via-IR pipeline. Inline assembly blocks are never optimized in isolation when using that pipeline. Instead they are optimized as a part of the whole Yul input. However, the legacy code generation pipeline (which is still the default) runs the Yul optimizer individually on an inline assembly block if the block does not refer to any local variables defined in the surrounding Solidity code. Consequently, memory writes in such inline assembly blocks are removed as well, if the written memory is never read from in the same assembly block, even if the written memory is accessed later, for example by a subsequent inline assembly block.\",\n \"link\": \"https://blog.soliditylang.org/2022/06/15/inline-assembly-memory-side-effects-bug/\",\n \"introduced\": \"0.8.13\",\n \"fixed\": \"0.8.15\",\n \"severity\": \"medium\",\n \"conditions\": {\n \"yulOptimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2022-3\",\n \"name\": \"DataLocationChangeInInternalOverride\",\n \"summary\": \"It was possible to change the data location of the parameters or return variables from ``calldata`` to ``memory`` and vice-versa while overriding internal and public functions. This caused invalid code to be generated when calling such a function internally through virtual function calls.\",\n \"description\": \"When calling external functions, it is irrelevant if the data location of the parameters is ``calldata`` or ``memory``, the encoding of the data does not change. Because of that, changing the data location when overriding external functions is allowed. The compiler incorrectly also allowed a change in the data location for overriding public and internal functions. Since public functions can be called internally as well as externally, this causes invalid code to be generated when such an incorrectly overridden function is called internally through the base contract. The caller provides a memory pointer, but the called function interprets it as a calldata pointer or vice-versa.\",\n \"link\": \"https://blog.soliditylang.org/2022/05/17/data-location-inheritance-bug/\",\n \"introduced\": \"0.6.9\",\n \"fixed\": \"0.8.14\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2022-2\",\n \"name\": \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"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()``.\",\n \"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).\",\n \"link\": \"https://blog.soliditylang.org/2022/05/17/calldata-reencode-size-check-bug/\",\n \"introduced\": \"0.5.8\",\n \"fixed\": \"0.8.14\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2022-1\",\n \"name\": \"AbiEncodeCallLiteralAsFixedBytesBug\",\n \"summary\": \"Literals used for a fixed length bytes parameter in ``abi.encodeCall`` were encoded incorrectly.\",\n \"description\": \"For the encoding, the compiler only considered the types of the expressions in the second argument of ``abi.encodeCall`` itself, but not the parameter types of the function given as first argument. In almost all cases the abi encoding of the type of the expression matches the abi encoding of the parameter type of the given function. This is because the type checker ensures the expression is implicitly convertible to the respective parameter type. However this is not true for number literals used for fixed bytes types shorter than 32 bytes, nor for string literals used for any fixed bytes type. Number literals were encoded as numbers instead of being shifted to become left-aligned. String literals were encoded as dynamically sized memory strings instead of being converted to a left-aligned bytes value.\",\n \"link\": \"https://blog.soliditylang.org/2022/03/16/encodecall-bug/\",\n \"introduced\": \"0.8.11\",\n \"fixed\": \"0.8.13\",\n \"severity\": \"very low\"\n\n },\n {\n \"uid\": \"SOL-2021-4\",\n \"name\": \"UserDefinedValueTypesBug\",\n \"summary\": \"User defined value types with underlying type shorter than 32 bytes used incorrect storage layout and wasted storage\",\n \"description\": \"The compiler did not correctly compute the storage layout of user defined value types based on types that are shorter than 32 bytes. It would always use a full storage slot for these types, even if the underlying type was shorter. This was wasteful and might have problems with tooling or contract upgrades.\",\n \"link\": \"https://blog.soliditylang.org/2021/09/29/user-defined-value-types-bug/\",\n \"introduced\": \"0.8.8\",\n \"fixed\": \"0.8.9\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2021-3\",\n \"name\": \"SignedImmutables\",\n \"summary\": \"Immutable variables of signed integer type shorter than 256 bits can lead to values with invalid higher order bits if inline assembly is used.\",\n \"description\": \"When immutable variables of signed integer type shorter than 256 bits are read, their higher order bits were unconditionally set to zero. The correct operation would be to sign-extend the value, i.e. set the higher order bits to one if the sign bit is one. This sign-extension is performed by Solidity just prior to when it matters, i.e. when a value is stored in memory, when it is compared or when a division is performed. Because of that, to our knowledge, the only way to access the value in its unclean state is by reading it through inline assembly.\",\n \"link\": \"https://blog.soliditylang.org/2021/09/29/signed-immutables-bug/\",\n \"introduced\": \"0.6.5\",\n \"fixed\": \"0.8.9\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2021-2\",\n \"name\": \"ABIDecodeTwoDimensionalArrayMemory\",\n \"summary\": \"If used on memory byte arrays, result of the function ``abi.decode`` can depend on the contents of memory outside of the actual byte array that is decoded.\",\n \"description\": \"The ABI specification uses pointers to data areas for everything that is dynamically-sized. When decoding data from memory (instead of calldata), the ABI decoder did not properly validate some of these pointers. More specifically, it was possible to use large values for the pointers inside arrays such that computing the offset resulted in an undetected overflow. This could lead to these pointers targeting areas in memory outside of the actual area to be decoded. This way, it was possible for ``abi.decode`` to return different values for the same encoded byte array.\",\n \"link\": \"https://blog.soliditylang.org/2021/04/21/decoding-from-memory-bug/\",\n \"introduced\": \"0.4.16\",\n \"fixed\": \"0.8.4\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n },\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2021-1\",\n \"name\": \"KeccakCaching\",\n \"summary\": \"The bytecode optimizer incorrectly reused previously evaluated Keccak-256 hashes. You are unlikely to be affected if you do not compute Keccak-256 hashes in inline assembly.\",\n \"description\": \"Solidity's bytecode optimizer has a step that can compute Keccak-256 hashes, if the contents of the memory are known during compilation time. This step also has a mechanism to determine that two Keccak-256 hashes are equal even if the values in memory are not known during compile time. This mechanism had a bug where Keccak-256 of the same memory content, but different sizes were considered equal. More specifically, ``keccak256(mpos1, length1)`` and ``keccak256(mpos2, length2)`` in some cases were considered equal if ``length1`` and ``length2``, when rounded up to nearest multiple of 32 were the same, and when the memory contents at ``mpos1`` and ``mpos2`` can be deduced to be equal. You maybe affected if you compute multiple Keccak-256 hashes of the same content, but with different lengths inside inline assembly. You are unaffected if your code uses ``keccak256`` with a length that is not a compile-time constant or if it is always a multiple of 32.\",\n \"link\": \"https://blog.soliditylang.org/2021/03/23/keccak-optimizer-bug/\",\n \"fixed\": \"0.8.3\",\n \"conditions\": {\n \"optimizer\": true\n },\n \"severity\": \"medium\"\n },\n {\n \"uid\": \"SOL-2020-11\",\n \"name\": \"EmptyByteArrayCopy\",\n \"summary\": \"Copying an empty byte array (or string) from memory or calldata to storage can result in data corruption if the target array's length is increased subsequently without storing new data.\",\n \"description\": \"The routine that copies byte arrays from memory or calldata to storage stores unrelated data from after the source array in the storage slot if the source array is empty. If the storage array's length is subsequently increased either by using ``.push()`` or by assigning to its ``.length`` attribute (only before 0.6.0), the newly created byte array elements will not be zero-initialized, but contain the unrelated data. You are not affected if you do not assign to ``.length`` and do not use ``.push()`` on byte arrays, or only use ``.push()`` or manually initialize the new elements.\",\n \"link\": \"https://blog.soliditylang.org/2020/10/19/empty-byte-array-copy-bug/\",\n \"fixed\": \"0.7.4\",\n \"severity\": \"medium\"\n },\n {\n \"uid\": \"SOL-2020-10\",\n \"name\": \"DynamicArrayCleanup\",\n \"summary\": \"When assigning a dynamically-sized array with types of size at most 16 bytes in storage causing the assigned array to shrink, some parts of deleted slots were not zeroed out.\",\n \"description\": \"Consider a dynamically-sized array in storage whose base-type is small enough such that multiple values can be packed into a single slot, such as `uint128[]`. Let us define its length to be `l`. When this array gets assigned from another array with a smaller length, say `m`, the slots between elements `m` and `l` have to be cleaned by zeroing them out. However, this cleaning was not performed properly. Specifically, after the slot corresponding to `m`, only the first packed value was cleaned up. If this array gets resized to a length larger than `m`, the indices corresponding to the unclean parts of the slot contained the original value, instead of 0. The resizing here is performed by assigning to the array `length`, by a `push()` or via inline assembly. You are not affected if you are only using `.push()` or if you assign a value (even zero) to the new elements after increasing the length of the array.\",\n \"link\": \"https://blog.soliditylang.org/2020/10/07/solidity-dynamic-array-cleanup-bug/\",\n \"fixed\": \"0.7.3\",\n \"severity\": \"medium\"\n },\n {\n \"uid\": \"SOL-2020-9\",\n \"name\": \"FreeFunctionRedefinition\",\n \"summary\": \"The compiler does not flag an error when two or more free functions with the same name and parameter types are defined in a source unit or when an imported free function alias shadows another free function with a different name but identical parameter types.\",\n \"description\": \"In contrast to functions defined inside contracts, free functions with identical names and parameter types did not create an error. Both definition of free functions with identical name and parameter types and an imported free function with an alias that shadows another function with a different name but identical parameter types were permitted due to which a call to either the multiply defined free function or the imported free function alias within a contract led to the execution of that free function which was defined first within the source unit. Subsequently defined identical free function definitions were silently ignored and their code generation was skipped.\",\n \"introduced\": \"0.7.1\",\n \"fixed\": \"0.7.2\",\n \"severity\": \"low\"\n },\n {\n \"uid\": \"SOL-2020-8\",\n \"name\": \"UsingForCalldata\",\n \"summary\": \"Function calls to internal library functions with calldata parameters called via ``using for`` can result in invalid data being read.\",\n \"description\": \"Function calls to internal library functions using the ``using for`` mechanism copied all calldata parameters to memory first and passed them on like that, regardless of whether it was an internal or an external call. Due to that, the called function would receive a memory pointer that is interpreted as a calldata pointer. Since dynamically sized arrays are passed using two stack slots for calldata, but only one for memory, this can lead to stack corruption. An affected library call will consider the JUMPDEST to which it is supposed to return as part of its arguments and will instead jump out to whatever was on the stack before the call.\",\n \"introduced\": \"0.6.9\",\n \"fixed\": \"0.6.10\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2020-7\",\n \"name\": \"MissingEscapingInFormatting\",\n \"summary\": \"String literals containing double backslash characters passed directly to external or encoding function calls can lead to a different string being used when ABIEncoderV2 is enabled.\",\n \"description\": \"When ABIEncoderV2 is enabled, string literals passed directly to encoding functions or external function calls are stored as strings in the intermediate code. Characters outside the printable range are handled correctly, but backslashes are not escaped in this procedure. This leads to double backslashes being reduced to single backslashes and consequently re-interpreted as escapes potentially resulting in a different string being encoded.\",\n \"introduced\": \"0.5.14\",\n \"fixed\": \"0.6.8\",\n \"severity\": \"very low\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n }\n },\n {\n \"uid\": \"SOL-2020-6\",\n \"name\": \"ArraySliceDynamicallyEncodedBaseType\",\n \"summary\": \"Accessing array slices of arrays with dynamically encoded base types (e.g. multi-dimensional arrays) can result in invalid data being read.\",\n \"description\": \"For arrays with dynamically sized base types, index range accesses that use a start expression that is non-zero will result in invalid array slices. Any index access to such array slices will result in data being read from incorrect calldata offsets. Array slices are only supported for dynamic calldata types and all problematic type require ABIEncoderV2 to be enabled.\",\n \"introduced\": \"0.6.0\",\n \"fixed\": \"0.6.8\",\n \"severity\": \"very low\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n }\n },\n {\n \"uid\": \"SOL-2020-5\",\n \"name\": \"ImplicitConstructorCallvalueCheck\",\n \"summary\": \"The creation code of a contract that does not define a constructor but has a base that does define a constructor did not revert for calls with non-zero value.\",\n \"description\": \"Starting from Solidity 0.4.5 the creation code of contracts without explicit payable constructor is supposed to contain a callvalue check that results in contract creation reverting, if non-zero value is passed. However, this check was missing in case no explicit constructor was defined in a contract at all, but the contract has a base that does define a constructor. In these cases it is possible to send value in a contract creation transaction or using inline assembly without revert, even though the creation code is supposed to be non-payable.\",\n \"introduced\": \"0.4.5\",\n \"fixed\": \"0.6.8\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2020-4\",\n \"name\": \"TupleAssignmentMultiStackSlotComponents\",\n \"summary\": \"Tuple assignments with components that occupy several stack slots, i.e. nested tuples, pointers to external functions or references to dynamically sized calldata arrays, can result in invalid values.\",\n \"description\": \"Tuple assignments did not correctly account for tuple components that occupy multiple stack slots in case the number of stack slots differs between left-hand-side and right-hand-side. This can either happen in the presence of nested tuples or if the right-hand-side contains external function pointers or references to dynamic calldata arrays, while the left-hand-side contains an omission.\",\n \"introduced\": \"0.1.6\",\n \"fixed\": \"0.6.6\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2020-3\",\n \"name\": \"MemoryArrayCreationOverflow\",\n \"summary\": \"The creation of very large memory arrays can result in overlapping memory regions and thus memory corruption.\",\n \"description\": \"No runtime overflow checks were performed for the length of memory arrays during creation. In cases for which the memory size of an array in bytes, i.e. the array length times 32, is larger than 2^256-1, the memory allocation will overflow, potentially resulting in overlapping memory areas. The length of the array is still stored correctly, so copying or iterating over such an array will result in out-of-gas.\",\n \"link\": \"https://blog.soliditylang.org/2020/04/06/memory-creation-overflow-bug/\",\n \"introduced\": \"0.2.0\",\n \"fixed\": \"0.6.5\",\n \"severity\": \"low\"\n },\n {\n \"uid\": \"SOL-2020-1\",\n \"name\": \"YulOptimizerRedundantAssignmentBreakContinue\",\n \"summary\": \"The Yul optimizer can remove essential assignments to variables declared inside for loops when Yul's continue or break statement is used. You are unlikely to be affected if you do not use inline assembly with for loops and continue and break statements.\",\n \"description\": \"The Yul optimizer has a stage that removes assignments to variables that are overwritten again or are not used in all following control-flow branches. This logic incorrectly removes such assignments to variables declared inside a for loop if they can be removed in a control-flow branch that ends with ``break`` or ``continue`` even though they cannot be removed in other control-flow branches. Variables declared outside of the respective for loop are not affected.\",\n \"introduced\": \"0.6.0\",\n \"fixed\": \"0.6.1\",\n \"severity\": \"medium\",\n \"conditions\": {\n \"yulOptimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2020-2\",\n \"name\": \"privateCanBeOverridden\",\n \"summary\": \"Private methods can be overridden by inheriting contracts.\",\n \"description\": \"While private methods of base contracts are not visible and cannot be called directly from the derived contract, it is still possible to declare a function of the same name and type and thus change the behaviour of the base contract's function.\",\n \"introduced\": \"0.3.0\",\n \"fixed\": \"0.5.17\",\n \"severity\": \"low\"\n },\n {\n \"uid\": \"SOL-2020-1\",\n \"name\": \"YulOptimizerRedundantAssignmentBreakContinue0.5\",\n \"summary\": \"The Yul optimizer can remove essential assignments to variables declared inside for loops when Yul's continue or break statement is used. You are unlikely to be affected if you do not use inline assembly with for loops and continue and break statements.\",\n \"description\": \"The Yul optimizer has a stage that removes assignments to variables that are overwritten again or are not used in all following control-flow branches. This logic incorrectly removes such assignments to variables declared inside a for loop if they can be removed in a control-flow branch that ends with ``break`` or ``continue`` even though they cannot be removed in other control-flow branches. Variables declared outside of the respective for loop are not affected.\",\n \"introduced\": \"0.5.8\",\n \"fixed\": \"0.5.16\",\n \"severity\": \"low\",\n \"conditions\": {\n \"yulOptimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2019-10\",\n \"name\": \"ABIEncoderV2LoopYulOptimizer\",\n \"summary\": \"If both the experimental ABIEncoderV2 and the experimental Yul optimizer are activated, one component of the Yul optimizer may reuse data in memory that has been changed in the meantime.\",\n \"description\": \"The Yul optimizer incorrectly replaces ``mload`` and ``sload`` calls with values that have been previously written to the load location (and potentially changed in the meantime) if all of the following conditions are met: (1) there is a matching ``mstore`` or ``sstore`` call before; (2) the contents of memory or storage is only changed in a function that is called (directly or indirectly) in between the first store and the load call; (3) called function contains a for loop where the same memory location is changed in the condition or the post or body block. When used in Solidity mode, this can only happen if the experimental ABIEncoderV2 is activated and the experimental Yul optimizer has been activated manually in addition to the regular optimizer in the compiler settings.\",\n \"introduced\": \"0.5.14\",\n \"fixed\": \"0.5.15\",\n \"severity\": \"low\",\n \"conditions\": {\n \"ABIEncoderV2\": true,\n \"optimizer\": true,\n \"yulOptimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2019-9\",\n \"name\": \"ABIEncoderV2CalldataStructsWithStaticallySizedAndDynamicallyEncodedMembers\",\n \"summary\": \"Reading from calldata structs that contain dynamically encoded, but statically-sized members can result in incorrect values.\",\n \"description\": \"When a calldata struct contains a dynamically encoded, but statically-sized member, the offsets for all subsequent struct members are calculated incorrectly. All reads from such members will result in invalid values. Only calldata structs are affected, i.e. this occurs in external functions with such structs as argument. Using affected structs in storage or memory or as arguments to public functions on the other hand works correctly.\",\n \"introduced\": \"0.5.6\",\n \"fixed\": \"0.5.11\",\n \"severity\": \"low\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n }\n },\n {\n \"uid\": \"SOL-2019-8\",\n \"name\": \"SignedArrayStorageCopy\",\n \"summary\": \"Assigning an array of signed integers to a storage array of different type can lead to data corruption in that array.\",\n \"description\": \"In two's complement, negative integers have their higher order bits set. In order to fit into a shared storage slot, these have to be set to zero. When a conversion is done at the same time, the bits to set to zero were incorrectly determined from the source and not the target type. This means that such copy operations can lead to incorrect values being stored.\",\n \"link\": \"https://blog.soliditylang.org/2019/06/25/solidity-storage-array-bugs/\",\n \"introduced\": \"0.4.7\",\n \"fixed\": \"0.5.10\",\n \"severity\": \"low/medium\"\n },\n {\n \"uid\": \"SOL-2019-7\",\n \"name\": \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"summary\": \"Storage arrays containing structs or other statically-sized arrays are not read properly when directly encoded in external function calls or in abi.encode*.\",\n \"description\": \"When storage arrays whose elements occupy more than a single storage slot are directly encoded in external function calls or using abi.encode*, their elements are read in an overlapping manner, i.e. the element pointer is not properly advanced between reads. This is not a problem when the storage data is first copied to a memory variable or if the storage array only contains value types or dynamically-sized arrays.\",\n \"link\": \"https://blog.soliditylang.org/2019/06/25/solidity-storage-array-bugs/\",\n \"introduced\": \"0.4.16\",\n \"fixed\": \"0.5.10\",\n \"severity\": \"low\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n }\n },\n {\n \"uid\": \"SOL-2019-6\",\n \"name\": \"DynamicConstructorArgumentsClippedABIV2\",\n \"summary\": \"A contract's constructor that takes structs or arrays that contain dynamically-sized arrays reverts or decodes to invalid data.\",\n \"description\": \"During construction of a contract, constructor parameters are copied from the code section to memory for decoding. The amount of bytes to copy was calculated incorrectly in case all parameters are statically-sized but contain dynamically-sized arrays as struct members or inner arrays. Such types are only available if ABIEncoderV2 is activated.\",\n \"introduced\": \"0.4.16\",\n \"fixed\": \"0.5.9\",\n \"severity\": \"very low\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n }\n },\n {\n \"uid\": \"SOL-2019-5\",\n \"name\": \"UninitializedFunctionPointerInConstructor\",\n \"summary\": \"Calling uninitialized internal function pointers created in the constructor does not always revert and can cause unexpected behaviour.\",\n \"description\": \"Uninitialized internal function pointers point to a special piece of code that causes a revert when called. Jump target positions are different during construction and after deployment, but the code for setting this special jump target only considered the situation after deployment.\",\n \"introduced\": \"0.5.0\",\n \"fixed\": \"0.5.8\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2019-5\",\n \"name\": \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"summary\": \"Calling uninitialized internal function pointers created in the constructor does not always revert and can cause unexpected behaviour.\",\n \"description\": \"Uninitialized internal function pointers point to a special piece of code that causes a revert when called. Jump target positions are different during construction and after deployment, but the code for setting this special jump target only considered the situation after deployment.\",\n \"introduced\": \"0.4.5\",\n \"fixed\": \"0.4.26\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2019-4\",\n \"name\": \"IncorrectEventSignatureInLibraries\",\n \"summary\": \"Contract types used in events in libraries cause an incorrect event signature hash\",\n \"description\": \"Instead of using the type `address` in the hashed signature, the actual contract name was used, leading to a wrong hash in the logs.\",\n \"introduced\": \"0.5.0\",\n \"fixed\": \"0.5.8\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2019-4\",\n \"name\": \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"summary\": \"Contract types used in events in libraries cause an incorrect event signature hash\",\n \"description\": \"Instead of using the type `address` in the hashed signature, the actual contract name was used, leading to a wrong hash in the logs.\",\n \"introduced\": \"0.3.0\",\n \"fixed\": \"0.4.26\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2019-3\",\n \"name\": \"ABIEncoderV2PackedStorage\",\n \"summary\": \"Storage structs and arrays with types shorter than 32 bytes can cause data corruption if encoded directly from storage using the experimental ABIEncoderV2.\",\n \"description\": \"Elements of structs and arrays that are shorter than 32 bytes are not properly decoded from storage when encoded directly (i.e. not via a memory type) using ABIEncoderV2. This can cause corruption in the values themselves but can also overwrite other parts of the encoded data.\",\n \"link\": \"https://blog.soliditylang.org/2019/03/26/solidity-optimizer-and-abiencoderv2-bug/\",\n \"introduced\": \"0.5.0\",\n \"fixed\": \"0.5.7\",\n \"severity\": \"low\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n }\n },\n {\n \"uid\": \"SOL-2019-3\",\n \"name\": \"ABIEncoderV2PackedStorage_0.4.x\",\n \"summary\": \"Storage structs and arrays with types shorter than 32 bytes can cause data corruption if encoded directly from storage using the experimental ABIEncoderV2.\",\n \"description\": \"Elements of structs and arrays that are shorter than 32 bytes are not properly decoded from storage when encoded directly (i.e. not via a memory type) using ABIEncoderV2. This can cause corruption in the values themselves but can also overwrite other parts of the encoded data.\",\n \"link\": \"https://blog.soliditylang.org/2019/03/26/solidity-optimizer-and-abiencoderv2-bug/\",\n \"introduced\": \"0.4.19\",\n \"fixed\": \"0.4.26\",\n \"severity\": \"low\",\n \"conditions\": {\n \"ABIEncoderV2\": true\n }\n },\n {\n \"uid\": \"SOL-2019-2\",\n \"name\": \"IncorrectByteInstructionOptimization\",\n \"summary\": \"The optimizer incorrectly handles byte opcodes whose second argument is 31 or a constant expression that evaluates to 31. This can result in unexpected values.\",\n \"description\": \"The optimizer incorrectly handles byte opcodes that use the constant 31 as second argument. This can happen when performing index access on bytesNN types with a compile-time constant value (not index) of 31 or when using the byte opcode in inline assembly.\",\n \"link\": \"https://blog.soliditylang.org/2019/03/26/solidity-optimizer-and-abiencoderv2-bug/\",\n \"introduced\": \"0.5.5\",\n \"fixed\": \"0.5.7\",\n \"severity\": \"very low\",\n \"conditions\": {\n \"optimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2019-1\",\n \"name\": \"DoubleShiftSizeOverflow\",\n \"summary\": \"Double bitwise shifts by large constants whose sum overflows 256 bits can result in unexpected values.\",\n \"description\": \"Nested logical shift operations whose total shift size is 2**256 or more are incorrectly optimized. This only applies to shifts by numbers of bits that are compile-time constant expressions.\",\n \"link\": \"https://blog.soliditylang.org/2019/03/26/solidity-optimizer-and-abiencoderv2-bug/\",\n \"introduced\": \"0.5.5\",\n \"fixed\": \"0.5.6\",\n \"severity\": \"low\",\n \"conditions\": {\n \"optimizer\": true,\n \"evmVersion\": \">=constantinople\"\n }\n },\n {\n \"uid\": \"SOL-2018-4\",\n \"name\": \"ExpExponentCleanup\",\n \"summary\": \"Using the ** operator with an exponent of type shorter than 256 bits can result in unexpected values.\",\n \"description\": \"Higher order bits in the exponent are not properly cleaned before the EXP opcode is applied if the type of the exponent expression is smaller than 256 bits and not smaller than the type of the base. In that case, the result might be larger than expected if the exponent is assumed to lie within the value range of the type. Literal numbers as exponents are unaffected as are exponents or bases of type uint256.\",\n \"link\": \"https://blog.soliditylang.org/2018/09/13/solidity-bugfix-release/\",\n \"fixed\": \"0.4.25\",\n \"severity\": \"medium/high\",\n \"check\": {\"regex-source\": \"[^/]\\\\*\\\\* *[^/0-9 ]\"}\n },\n {\n \"uid\": \"SOL-2018-3\",\n \"name\": \"EventStructWrongData\",\n \"summary\": \"Using structs in events logged wrong data.\",\n \"description\": \"If a struct is used in an event, the address of the struct is logged instead of the actual data.\",\n \"link\": \"https://blog.soliditylang.org/2018/09/13/solidity-bugfix-release/\",\n \"introduced\": \"0.4.17\",\n \"fixed\": \"0.4.25\",\n \"severity\": \"very low\",\n \"check\": {\"ast-compact-json-path\": \"$..[?(@.nodeType === 'EventDefinition')]..[?(@.nodeType === 'UserDefinedTypeName' && @.typeDescriptions.typeString.startsWith('struct'))]\"}\n },\n {\n \"uid\": \"SOL-2018-2\",\n \"name\": \"NestedArrayFunctionCallDecoder\",\n \"summary\": \"Calling functions that return multi-dimensional fixed-size arrays can result in memory corruption.\",\n \"description\": \"If Solidity code calls a function that returns a multi-dimensional fixed-size array, array elements are incorrectly interpreted as memory pointers and thus can cause memory corruption if the return values are accessed. Calling functions with multi-dimensional fixed-size arrays is unaffected as is returning fixed-size arrays from function calls. The regular expression only checks if such functions are present, not if they are called, which is required for the contract to be affected.\",\n \"link\": \"https://blog.soliditylang.org/2018/09/13/solidity-bugfix-release/\",\n \"introduced\": \"0.1.4\",\n \"fixed\": \"0.4.22\",\n \"severity\": \"medium\",\n \"check\": {\"regex-source\": \"returns[^;{]*\\\\[\\\\s*[^\\\\] \\\\t\\\\r\\\\n\\\\v\\\\f][^\\\\]]*\\\\]\\\\s*\\\\[\\\\s*[^\\\\] \\\\t\\\\r\\\\n\\\\v\\\\f][^\\\\]]*\\\\][^{;]*[;{]\"}\n },\n {\n \"uid\": \"SOL-2018-1\",\n \"name\": \"OneOfTwoConstructorsSkipped\",\n \"summary\": \"If a contract has both a new-style constructor (using the constructor keyword) and an old-style constructor (a function with the same name as the contract) at the same time, one of them will be ignored.\",\n \"description\": \"If a contract has both a new-style constructor (using the constructor keyword) and an old-style constructor (a function with the same name as the contract) at the same time, one of them will be ignored. There will be a compiler warning about the old-style constructor, so contracts only using new-style constructors are fine.\",\n \"introduced\": \"0.4.22\",\n \"fixed\": \"0.4.23\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2017-5\",\n \"name\": \"ZeroFunctionSelector\",\n \"summary\": \"It is possible to craft the name of a function such that it is executed instead of the fallback function in very specific circumstances.\",\n \"description\": \"If a function has a selector consisting only of zeros, is payable and part of a contract that does not have a fallback function and at most five external functions in total, this function is called instead of the fallback function if Ether is sent to the contract without data.\",\n \"fixed\": \"0.4.18\",\n \"severity\": \"very low\"\n },\n {\n \"uid\": \"SOL-2017-4\",\n \"name\": \"DelegateCallReturnValue\",\n \"summary\": \"The low-level .delegatecall() does not return the execution outcome, but converts the value returned by the functioned called to a boolean instead.\",\n \"description\": \"The return value of the low-level .delegatecall() function is taken from a position in memory, where the call data or the return data resides. This value is interpreted as a boolean and put onto the stack. This means if the called function returns at least 32 zero bytes, .delegatecall() returns false even if the call was successful.\",\n \"introduced\": \"0.3.0\",\n \"fixed\": \"0.4.15\",\n \"severity\": \"low\"\n },\n {\n \"uid\": \"SOL-2017-3\",\n \"name\": \"ECRecoverMalformedInput\",\n \"summary\": \"The ecrecover() builtin can return garbage for malformed input.\",\n \"description\": \"The ecrecover precompile does not properly signal failure for malformed input (especially in the 'v' argument) and thus the Solidity function can return data that was previously present in the return area in memory.\",\n \"fixed\": \"0.4.14\",\n \"severity\": \"medium\"\n },\n {\n \"uid\": \"SOL-2017-2\",\n \"name\": \"SkipEmptyStringLiteral\",\n \"summary\": \"If \\\"\\\" is used in a function call, the following function arguments will not be correctly passed to the function.\",\n \"description\": \"If the empty string literal \\\"\\\" is used as an argument in a function call, it is skipped by the encoder. This has the effect that the encoding of all arguments following this is shifted left by 32 bytes and thus the function call data is corrupted.\",\n \"fixed\": \"0.4.12\",\n \"severity\": \"low\"\n },\n {\n \"uid\": \"SOL-2017-1\",\n \"name\": \"ConstantOptimizerSubtraction\",\n \"summary\": \"In some situations, the optimizer replaces certain numbers in the code with routines that compute different numbers.\",\n \"description\": \"The optimizer tries to represent any number in the bytecode by routines that compute them with less gas. For some special numbers, an incorrect routine is generated. This could allow an attacker to e.g. trick victims about a specific amount of ether, or function calls to call different functions (or none at all).\",\n \"link\": \"https://blog.soliditylang.org/2017/05/03/solidity-optimizer-bug/\",\n \"fixed\": \"0.4.11\",\n \"severity\": \"low\",\n \"conditions\": {\n \"optimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2016-11\",\n \"name\": \"IdentityPrecompileReturnIgnored\",\n \"summary\": \"Failure of the identity precompile was ignored.\",\n \"description\": \"Calls to the identity contract, which is used for copying memory, ignored its return value. On the public chain, calls to the identity precompile can be made in a way that they never fail, but this might be different on private chains.\",\n \"severity\": \"low\",\n \"fixed\": \"0.4.7\"\n },\n {\n \"uid\": \"SOL-2016-10\",\n \"name\": \"OptimizerStateKnowledgeNotResetForJumpdest\",\n \"summary\": \"The optimizer did not properly reset its internal state at jump destinations, which could lead to data corruption.\",\n \"description\": \"The optimizer performs symbolic execution at certain stages. At jump destinations, multiple code paths join and thus it has to compute a common state from the incoming edges. Computing this common state was simplified to just use the empty state, but this implementation was not done properly. This bug can cause data corruption.\",\n \"severity\": \"medium\",\n \"introduced\": \"0.4.5\",\n \"fixed\": \"0.4.6\",\n \"conditions\": {\n \"optimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2016-9\",\n \"name\": \"HighOrderByteCleanStorage\",\n \"summary\": \"For short types, the high order bytes were not cleaned properly and could overwrite existing data.\",\n \"description\": \"Types shorter than 32 bytes are packed together into the same 32 byte storage slot, but storage writes always write 32 bytes. For some types, the higher order bytes were not cleaned properly, which made it sometimes possible to overwrite a variable in storage when writing to another one.\",\n \"link\": \"https://blog.soliditylang.org/2016/11/01/security-alert-solidity-variables-can-overwritten-storage/\",\n \"severity\": \"high\",\n \"introduced\": \"0.1.6\",\n \"fixed\": \"0.4.4\"\n },\n {\n \"uid\": \"SOL-2016-8\",\n \"name\": \"OptimizerStaleKnowledgeAboutSHA3\",\n \"summary\": \"The optimizer did not properly reset its knowledge about SHA3 operations resulting in some hashes (also used for storage variable positions) not being calculated correctly.\",\n \"description\": \"The optimizer performs symbolic execution in order to save re-evaluating expressions whose value is already known. This knowledge was not properly reset across control flow paths and thus the optimizer sometimes thought that the result of a SHA3 operation is already present on the stack. This could result in data corruption by accessing the wrong storage slot.\",\n \"severity\": \"medium\",\n \"fixed\": \"0.4.3\",\n \"conditions\": {\n \"optimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2016-7\",\n \"name\": \"LibrariesNotCallableFromPayableFunctions\",\n \"summary\": \"Library functions threw an exception when called from a call that received Ether.\",\n \"description\": \"Library functions are protected against sending them Ether through a call. Since the DELEGATECALL opcode forwards the information about how much Ether was sent with a call, the library function incorrectly assumed that Ether was sent to the library and threw an exception.\",\n \"severity\": \"low\",\n \"introduced\": \"0.4.0\",\n \"fixed\": \"0.4.2\"\n },\n {\n \"uid\": \"SOL-2016-6\",\n \"name\": \"SendFailsForZeroEther\",\n \"summary\": \"The send function did not provide enough gas to the recipient if no Ether was sent with it.\",\n \"description\": \"The recipient of an Ether transfer automatically receives a certain amount of gas from the EVM to handle the transfer. In the case of a zero-transfer, this gas is not provided which causes the recipient to throw an exception.\",\n \"severity\": \"low\",\n \"fixed\": \"0.4.0\"\n },\n {\n \"uid\": \"SOL-2016-5\",\n \"name\": \"DynamicAllocationInfiniteLoop\",\n \"summary\": \"Dynamic allocation of an empty memory array caused an infinite loop and thus an exception.\",\n \"description\": \"Memory arrays can be created provided a length. If this length is zero, code was generated that did not terminate and thus consumed all gas.\",\n \"severity\": \"low\",\n \"fixed\": \"0.3.6\"\n },\n {\n \"uid\": \"SOL-2016-4\",\n \"name\": \"OptimizerClearStateOnCodePathJoin\",\n \"summary\": \"The optimizer did not properly reset its internal state at jump destinations, which could lead to data corruption.\",\n \"description\": \"The optimizer performs symbolic execution at certain stages. At jump destinations, multiple code paths join and thus it has to compute a common state from the incoming edges. Computing this common state was not done correctly. This bug can cause data corruption, but it is probably quite hard to use for targeted attacks.\",\n \"severity\": \"low\",\n \"fixed\": \"0.3.6\",\n \"conditions\": {\n \"optimizer\": true\n }\n },\n {\n \"uid\": \"SOL-2016-3\",\n \"name\": \"CleanBytesHigherOrderBits\",\n \"summary\": \"The higher order bits of short bytesNN types were not cleaned before comparison.\",\n \"description\": \"Two variables of type bytesNN were considered different if their higher order bits, which are not part of the actual value, were different. An attacker might use this to reach seemingly unreachable code paths by providing incorrectly formatted input data.\",\n \"severity\": \"medium/high\",\n \"fixed\": \"0.3.3\"\n },\n {\n \"uid\": \"SOL-2016-2\",\n \"name\": \"ArrayAccessCleanHigherOrderBits\",\n \"summary\": \"Access to array elements for arrays of types with less than 32 bytes did not correctly clean the higher order bits, causing corruption in other array elements.\",\n \"description\": \"Multiple elements of an array of values that are shorter than 17 bytes are packed into the same storage slot. Writing to a single element of such an array did not properly clean the higher order bytes and thus could lead to data corruption.\",\n \"severity\": \"medium/high\",\n \"fixed\": \"0.3.1\"\n },\n {\n \"uid\": \"SOL-2016-1\",\n \"name\": \"AncientCompiler\",\n \"summary\": \"This compiler version is ancient and might contain several undocumented or undiscovered bugs.\",\n \"description\": \"The list of bugs is only kept for compiler versions starting from 0.3.0, so older versions might contain undocumented bugs.\",\n \"severity\": \"high\",\n \"fixed\": \"0.3.0\"\n }\n]\n" }, { "path": "docs/bugs.rst", "content": ".. index:: Bugs\n\n.. _known_bugs:\n\n##################\nList of Known Bugs\n##################\n\nBelow, you can find a JSON-formatted list of some of the known security-relevant bugs in the\nSolidity compiler. The file itself is hosted in the `GitHub repository\n`_.\nThe list stretches back as far as version 0.3.0, bugs known to be present only\nin versions preceding that are not listed.\n\nThere is another file called `bugs_by_version.json\n`_,\nwhich can be used to check which bugs affect a specific version of the compiler.\n\nContract source verification tools and also other tools interacting with\ncontracts should consult this list according to the following criteria:\n\n- It is mildly suspicious if a contract was compiled with a nightly\n compiler version instead of a released version. This list does not keep\n track of unreleased or nightly versions.\n- It is also mildly suspicious if a contract was compiled with a version that was\n not the most recent at the time the contract was created. For contracts\n created from other contracts, you have to follow the creation chain\n back to a transaction and use the date of that transaction as creation date.\n- It is highly suspicious if a contract was compiled with a compiler that\n contains a known bug and the contract was created at a time where a newer\n compiler version containing a fix was already released.\n\nThe JSON file of known bugs below is an array of objects, one for each bug,\nwith the following keys:\n\nuid\n Unique identifier given to the bug in the form of ``SOL--``.\n It is possible that multiple entries exists with the same uid. This means\n multiple version ranges are affected by the same bug.\nname\n Unique name given to the bug\nsummary\n Short description of the bug\ndescription\n Detailed description of the bug\nlink\n URL of a website with more detailed information, optional\nintroduced\n The first published compiler version that contained the bug, optional\nfixed\n The first published compiler version that did not contain the bug anymore\npublish\n The date at which the bug became known publicly, optional\nseverity\n Severity of the bug: very low, low, medium, high. Takes into account\n discoverability in contract tests, likelihood of occurrence and\n potential damage by exploits.\nconditions\n Conditions that have to be met to trigger the bug. The following\n keys can be used:\n ``optimizer``, Boolean value which\n means that the optimizer has to be switched on to enable the bug.\n ``evmVersion``, a string that indicates which EVM version compiler\n settings trigger the bug. The string can contain comparison\n operators. For example, ``\">=constantinople\"`` means that the bug\n is present when the EVM version is set to ``constantinople`` or\n later.\n If no conditions are given, assume that the bug is present.\ncheck\n This field contains different checks that report whether the smart contract\n contains the bug or not. The first type of check are JavaScript regular\n expressions that are to be matched against the source code (\"source-regex\")\n if the bug is present. If there is no match, then the bug is very likely\n not present. If there is a match, the bug might be present. For improved\n accuracy, the checks should be applied to the source code after stripping\n comments.\n The second type of check are patterns to be checked on the compact AST of\n the Solidity program (\"ast-compact-json-path\"). The specified search query\n is a `JsonPath `_ expression.\n If at least one path of the Solidity AST matches the query, the bug is\n likely present.\n\n.. literalinclude:: bugs.json\n :language: js\n" }, { "path": "docs/bugs_by_version.json", "content": "{\n \"0.1.0\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ExpExponentCleanup\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-07-10\"\n },\n \"0.1.1\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ExpExponentCleanup\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-08-04\"\n },\n \"0.1.2\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ExpExponentCleanup\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-08-20\"\n },\n \"0.1.3\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ExpExponentCleanup\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-09-25\"\n },\n \"0.1.4\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-09-30\"\n },\n \"0.1.5\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-10-07\"\n },\n \"0.1.6\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-10-16\"\n },\n \"0.1.7\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-11-17\"\n },\n \"0.2.0\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2015-12-02\"\n },\n \"0.2.1\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2016-01-30\"\n },\n \"0.2.2\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\",\n \"AncientCompiler\"\n ],\n \"released\": \"2016-02-17\"\n },\n \"0.3.0\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\",\n \"ArrayAccessCleanHigherOrderBits\"\n ],\n \"released\": \"2016-03-11\"\n },\n \"0.3.1\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\"\n ],\n \"released\": \"2016-03-31\"\n },\n \"0.3.2\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\",\n \"CleanBytesHigherOrderBits\"\n ],\n \"released\": \"2016-04-18\"\n },\n \"0.3.3\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\"\n ],\n \"released\": \"2016-05-27\"\n },\n \"0.3.4\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\"\n ],\n \"released\": \"2016-05-31\"\n },\n \"0.3.5\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\",\n \"DynamicAllocationInfiniteLoop\",\n \"OptimizerClearStateOnCodePathJoin\"\n ],\n \"released\": \"2016-06-10\"\n },\n \"0.3.6\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"SendFailsForZeroEther\"\n ],\n \"released\": \"2016-08-10\"\n },\n \"0.4.0\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"LibrariesNotCallableFromPayableFunctions\"\n ],\n \"released\": \"2016-09-08\"\n },\n \"0.4.1\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\",\n \"LibrariesNotCallableFromPayableFunctions\"\n ],\n \"released\": \"2016-09-09\"\n },\n \"0.4.10\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\"\n ],\n \"released\": \"2017-03-15\"\n },\n \"0.4.11\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\"\n ],\n \"released\": \"2017-05-03\"\n },\n \"0.4.12\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\"\n ],\n \"released\": \"2017-07-03\"\n },\n \"0.4.13\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\"\n ],\n \"released\": \"2017-07-06\"\n },\n \"0.4.14\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\"\n ],\n \"released\": \"2017-07-31\"\n },\n \"0.4.15\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\"\n ],\n \"released\": \"2017-08-08\"\n },\n \"0.4.16\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\"\n ],\n \"released\": \"2017-08-24\"\n },\n \"0.4.17\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"EventStructWrongData\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\"\n ],\n \"released\": \"2017-09-21\"\n },\n \"0.4.18\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"EventStructWrongData\",\n \"NestedArrayFunctionCallDecoder\"\n ],\n \"released\": \"2017-10-18\"\n },\n \"0.4.19\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ABIEncoderV2PackedStorage_0.4.x\",\n \"ExpExponentCleanup\",\n \"EventStructWrongData\",\n \"NestedArrayFunctionCallDecoder\"\n ],\n \"released\": \"2017-11-30\"\n },\n \"0.4.2\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\",\n \"OptimizerStaleKnowledgeAboutSHA3\"\n ],\n \"released\": \"2016-09-17\"\n },\n \"0.4.20\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ABIEncoderV2PackedStorage_0.4.x\",\n \"ExpExponentCleanup\",\n \"EventStructWrongData\",\n \"NestedArrayFunctionCallDecoder\"\n ],\n \"released\": \"2018-02-14\"\n },\n \"0.4.21\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ABIEncoderV2PackedStorage_0.4.x\",\n \"ExpExponentCleanup\",\n \"EventStructWrongData\",\n \"NestedArrayFunctionCallDecoder\"\n ],\n \"released\": \"2018-03-07\"\n },\n \"0.4.22\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ABIEncoderV2PackedStorage_0.4.x\",\n \"ExpExponentCleanup\",\n \"EventStructWrongData\",\n \"OneOfTwoConstructorsSkipped\"\n ],\n \"released\": \"2018-04-16\"\n },\n \"0.4.23\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ABIEncoderV2PackedStorage_0.4.x\",\n \"ExpExponentCleanup\",\n \"EventStructWrongData\"\n ],\n \"released\": \"2018-04-19\"\n },\n \"0.4.24\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ABIEncoderV2PackedStorage_0.4.x\",\n \"ExpExponentCleanup\",\n \"EventStructWrongData\"\n ],\n \"released\": \"2018-05-16\"\n },\n \"0.4.25\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ABIEncoderV2PackedStorage_0.4.x\"\n ],\n \"released\": \"2018-09-12\"\n },\n \"0.4.26\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\"\n ],\n \"released\": \"2019-04-29\"\n },\n \"0.4.3\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"HighOrderByteCleanStorage\"\n ],\n \"released\": \"2016-10-25\"\n },\n \"0.4.4\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\"\n ],\n \"released\": \"2016-10-31\"\n },\n \"0.4.5\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\",\n \"OptimizerStateKnowledgeNotResetForJumpdest\"\n ],\n \"released\": \"2016-11-21\"\n },\n \"0.4.6\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\",\n \"IdentityPrecompileReturnIgnored\"\n ],\n \"released\": \"2016-11-22\"\n },\n \"0.4.7\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\"\n ],\n \"released\": \"2016-12-15\"\n },\n \"0.4.8\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\"\n ],\n \"released\": \"2017-01-13\"\n },\n \"0.4.9\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"UninitializedFunctionPointerInConstructor_0.4.x\",\n \"IncorrectEventSignatureInLibraries_0.4.x\",\n \"ExpExponentCleanup\",\n \"NestedArrayFunctionCallDecoder\",\n \"ZeroFunctionSelector\",\n \"DelegateCallReturnValue\",\n \"ECRecoverMalformedInput\",\n \"SkipEmptyStringLiteral\",\n \"ConstantOptimizerSubtraction\"\n ],\n \"released\": \"2017-01-31\"\n },\n \"0.5.0\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor\",\n \"IncorrectEventSignatureInLibraries\",\n \"ABIEncoderV2PackedStorage\"\n ],\n \"released\": \"2018-11-13\"\n },\n \"0.5.1\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor\",\n \"IncorrectEventSignatureInLibraries\",\n \"ABIEncoderV2PackedStorage\"\n ],\n \"released\": \"2018-12-03\"\n },\n \"0.5.10\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"YulOptimizerRedundantAssignmentBreakContinue0.5\",\n \"ABIEncoderV2CalldataStructsWithStaticallySizedAndDynamicallyEncodedMembers\"\n ],\n \"released\": \"2019-06-25\"\n },\n \"0.5.11\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"YulOptimizerRedundantAssignmentBreakContinue0.5\"\n ],\n \"released\": \"2019-08-12\"\n },\n \"0.5.12\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"YulOptimizerRedundantAssignmentBreakContinue0.5\"\n ],\n \"released\": \"2019-10-01\"\n },\n \"0.5.13\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"YulOptimizerRedundantAssignmentBreakContinue0.5\"\n ],\n \"released\": \"2019-11-14\"\n },\n \"0.5.14\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"YulOptimizerRedundantAssignmentBreakContinue0.5\",\n \"ABIEncoderV2LoopYulOptimizer\"\n ],\n \"released\": \"2019-12-09\"\n },\n \"0.5.15\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"YulOptimizerRedundantAssignmentBreakContinue0.5\"\n ],\n \"released\": \"2019-12-17\"\n },\n \"0.5.16\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\"\n ],\n \"released\": \"2020-01-02\"\n },\n \"0.5.17\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\"\n ],\n \"released\": \"2020-03-17\"\n },\n \"0.5.2\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor\",\n \"IncorrectEventSignatureInLibraries\",\n \"ABIEncoderV2PackedStorage\"\n ],\n \"released\": \"2018-12-19\"\n },\n \"0.5.3\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor\",\n \"IncorrectEventSignatureInLibraries\",\n \"ABIEncoderV2PackedStorage\"\n ],\n \"released\": \"2019-01-22\"\n },\n \"0.5.4\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor\",\n \"IncorrectEventSignatureInLibraries\",\n \"ABIEncoderV2PackedStorage\"\n ],\n \"released\": \"2019-02-12\"\n },\n \"0.5.5\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor\",\n \"IncorrectEventSignatureInLibraries\",\n \"ABIEncoderV2PackedStorage\",\n \"IncorrectByteInstructionOptimization\",\n \"DoubleShiftSizeOverflow\"\n ],\n \"released\": \"2019-03-05\"\n },\n \"0.5.6\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"ABIEncoderV2CalldataStructsWithStaticallySizedAndDynamicallyEncodedMembers\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor\",\n \"IncorrectEventSignatureInLibraries\",\n \"ABIEncoderV2PackedStorage\",\n \"IncorrectByteInstructionOptimization\"\n ],\n \"released\": \"2019-03-13\"\n },\n \"0.5.7\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"DirtyBytesArrayToStorage\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"ABIEncoderV2CalldataStructsWithStaticallySizedAndDynamicallyEncodedMembers\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\",\n \"UninitializedFunctionPointerInConstructor\",\n \"IncorrectEventSignatureInLibraries\"\n ],\n \"released\": \"2019-03-26\"\n },\n \"0.5.8\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"YulOptimizerRedundantAssignmentBreakContinue0.5\",\n \"ABIEncoderV2CalldataStructsWithStaticallySizedAndDynamicallyEncodedMembers\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\",\n \"DynamicConstructorArgumentsClippedABIV2\"\n ],\n \"released\": \"2019-04-30\"\n },\n \"0.5.9\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"privateCanBeOverridden\",\n \"YulOptimizerRedundantAssignmentBreakContinue0.5\",\n \"ABIEncoderV2CalldataStructsWithStaticallySizedAndDynamicallyEncodedMembers\",\n \"SignedArrayStorageCopy\",\n \"ABIEncoderV2StorageArrayWithMultiSlotElement\"\n ],\n \"released\": \"2019-05-28\"\n },\n \"0.6.0\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ArraySliceDynamicallyEncodedBaseType\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\",\n \"YulOptimizerRedundantAssignmentBreakContinue\"\n ],\n \"released\": \"2019-12-17\"\n },\n \"0.6.1\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ArraySliceDynamicallyEncodedBaseType\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\"\n ],\n \"released\": \"2020-01-02\"\n },\n \"0.6.10\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\"\n ],\n \"released\": \"2020-06-11\"\n },\n \"0.6.11\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\"\n ],\n \"released\": \"2020-07-07\"\n },\n \"0.6.12\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\"\n ],\n \"released\": \"2020-07-22\"\n },\n \"0.6.2\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ArraySliceDynamicallyEncodedBaseType\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\"\n ],\n \"released\": \"2020-01-27\"\n },\n \"0.6.3\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ArraySliceDynamicallyEncodedBaseType\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\"\n ],\n \"released\": \"2020-02-18\"\n },\n \"0.6.4\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ArraySliceDynamicallyEncodedBaseType\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\",\n \"MemoryArrayCreationOverflow\"\n ],\n \"released\": \"2020-03-10\"\n },\n \"0.6.5\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ArraySliceDynamicallyEncodedBaseType\",\n \"ImplicitConstructorCallvalueCheck\",\n \"TupleAssignmentMultiStackSlotComponents\"\n ],\n \"released\": \"2020-04-06\"\n },\n \"0.6.6\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ArraySliceDynamicallyEncodedBaseType\",\n \"ImplicitConstructorCallvalueCheck\"\n ],\n \"released\": \"2020-04-09\"\n },\n \"0.6.7\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"MissingEscapingInFormatting\",\n \"ArraySliceDynamicallyEncodedBaseType\",\n \"ImplicitConstructorCallvalueCheck\"\n ],\n \"released\": \"2020-05-04\"\n },\n \"0.6.8\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\"\n ],\n \"released\": \"2020-05-14\"\n },\n \"0.6.9\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"UsingForCalldata\"\n ],\n \"released\": \"2020-06-04\"\n },\n \"0.7.0\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\"\n ],\n \"released\": \"2020-07-28\"\n },\n \"0.7.1\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\",\n \"FreeFunctionRedefinition\"\n ],\n \"released\": \"2020-09-02\"\n },\n \"0.7.2\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\",\n \"DynamicArrayCleanup\"\n ],\n \"released\": \"2020-09-28\"\n },\n \"0.7.3\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\",\n \"EmptyByteArrayCopy\"\n ],\n \"released\": \"2020-10-07\"\n },\n \"0.7.4\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\"\n ],\n \"released\": \"2020-10-19\"\n },\n \"0.7.5\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\"\n ],\n \"released\": \"2020-11-18\"\n },\n \"0.7.6\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\"\n ],\n \"released\": \"2020-12-16\"\n },\n \"0.8.0\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\"\n ],\n \"released\": \"2020-12-16\"\n },\n \"0.8.1\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\"\n ],\n \"released\": \"2021-01-27\"\n },\n \"0.8.10\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\"\n ],\n \"released\": \"2021-11-09\"\n },\n \"0.8.11\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"AbiEncodeCallLiteralAsFixedBytesBug\"\n ],\n \"released\": \"2021-12-20\"\n },\n \"0.8.12\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"AbiEncodeCallLiteralAsFixedBytesBug\"\n ],\n \"released\": \"2022-02-16\"\n },\n \"0.8.13\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"StorageWriteRemovalBeforeConditionalTermination\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"InlineAssemblyMemorySideEffects\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\"\n ],\n \"released\": \"2022-03-16\"\n },\n \"0.8.14\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"StorageWriteRemovalBeforeConditionalTermination\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"InlineAssemblyMemorySideEffects\"\n ],\n \"released\": \"2022-05-17\"\n },\n \"0.8.15\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"StorageWriteRemovalBeforeConditionalTermination\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\"\n ],\n \"released\": \"2022-06-15\"\n },\n \"0.8.16\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"StorageWriteRemovalBeforeConditionalTermination\"\n ],\n \"released\": \"2022-08-08\"\n },\n \"0.8.17\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\"\n ],\n \"released\": \"2022-09-08\"\n },\n \"0.8.18\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\"\n ],\n \"released\": \"2023-02-01\"\n },\n \"0.8.19\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\"\n ],\n \"released\": \"2023-02-22\"\n },\n \"0.8.2\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\",\n \"KeccakCaching\"\n ],\n \"released\": \"2021-03-02\"\n },\n \"0.8.20\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\"\n ],\n \"released\": \"2023-05-10\"\n },\n \"0.8.21\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\"\n ],\n \"released\": \"2023-07-19\"\n },\n \"0.8.22\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\"\n ],\n \"released\": \"2023-10-25\"\n },\n \"0.8.23\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2023-11-08\"\n },\n \"0.8.24\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2024-01-25\"\n },\n \"0.8.25\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2024-03-14\"\n },\n \"0.8.26\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2024-05-21\"\n },\n \"0.8.27\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2024-09-04\"\n },\n \"0.8.28\": {\n \"bugs\": [\n \"TransientStorageClearingHelperCollision\",\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2024-10-09\"\n },\n \"0.8.29\": {\n \"bugs\": [\n \"TransientStorageClearingHelperCollision\",\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2025-03-12\"\n },\n \"0.8.3\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\",\n \"ABIDecodeTwoDimensionalArrayMemory\"\n ],\n \"released\": \"2021-03-23\"\n },\n \"0.8.30\": {\n \"bugs\": [\n \"TransientStorageClearingHelperCollision\",\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2025-05-07\"\n },\n \"0.8.31\": {\n \"bugs\": [\n \"TransientStorageClearingHelperCollision\",\n \"LostStorageArrayWriteOnSlotOverflow\"\n ],\n \"released\": \"2025-12-03\"\n },\n \"0.8.32\": {\n \"bugs\": [\n \"TransientStorageClearingHelperCollision\"\n ],\n \"released\": \"2025-12-18\"\n },\n \"0.8.33\": {\n \"bugs\": [\n \"TransientStorageClearingHelperCollision\"\n ],\n \"released\": \"2025-12-18\"\n },\n \"0.8.34\": {\n \"bugs\": [],\n \"released\": \"2026-02-18\"\n },\n \"0.8.4\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\"\n ],\n \"released\": \"2021-04-21\"\n },\n \"0.8.5\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\"\n ],\n \"released\": \"2021-06-10\"\n },\n \"0.8.6\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\"\n ],\n \"released\": \"2021-06-22\"\n },\n \"0.8.7\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"SignedImmutables\"\n ],\n \"released\": \"2021-08-11\"\n },\n \"0.8.8\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\",\n \"UserDefinedValueTypesBug\",\n \"SignedImmutables\"\n ],\n \"released\": \"2021-09-27\"\n },\n \"0.8.9\": {\n \"bugs\": [\n \"LostStorageArrayWriteOnSlotOverflow\",\n \"VerbatimInvalidDeduplication\",\n \"FullInlinerNonExpressionSplitArgumentEvaluationOrder\",\n \"MissingSideEffectsOnSelectorAccess\",\n \"AbiReencodingHeadOverflowWithStaticArrayCleanup\",\n \"DirtyBytesArrayToStorage\",\n \"DataLocationChangeInInternalOverride\",\n \"NestedCalldataArrayAbiReencodingSizeValidation\"\n ],\n \"released\": \"2021-09-29\"\n }\n}" }, { "path": "docs/cheatsheet.rst", "content": "**********\nCheatsheet\n**********\n\n.. index:: operator;precedence\n\nOrder of Precedence of Operators\n================================\n\n.. include:: types/operator-precedence-table.rst\n\n.. index:: abi;decode, abi;encode, abi;encodePacked, abi;encodeWithSelector, abi;encodeCall, abi;encodeWithSignature\n\nABI Encoding and Decoding Functions\n===================================\n\n- ``abi.decode(bytes memory encodedData, (...)) returns (...)``: :ref:`ABI `-decodes\n the provided data. The types are given in parentheses as second argument.\n Example: ``(uint a, uint[2] memory b, bytes memory c) = abi.decode(data, (uint, uint[2], bytes))``\n- ``abi.encode(...) returns (bytes memory)``: :ref:`ABI `-encodes the given arguments\n- ``abi.encodePacked(...) returns (bytes memory)``: Performs :ref:`packed encoding ` of\n the given arguments. Note that this encoding can be ambiguous!\n- ``abi.encodeWithSelector(bytes4 selector, ...) returns (bytes memory)``: :ref:`ABI `-encodes\n the given arguments starting from the second and prepends the given four-byte selector\n- ``abi.encodeCall(function functionPointer, (...)) returns (bytes memory)``: ABI-encodes a call to ``functionPointer`` with the arguments found in the\n tuple. Performs a full type-check, ensuring the types match the function signature. Result equals ``abi.encodeWithSelector(functionPointer.selector, ...)``\n- ``abi.encodeWithSignature(string memory signature, ...) returns (bytes memory)``: Equivalent\n to ``abi.encodeWithSelector(bytes4(keccak256(bytes(signature))), ...)``\n\n.. index:: bytes;concat, string;concat\n\nMembers of ``bytes`` and ``string``\n====================================\n\n- ``bytes.concat(...) returns (bytes memory)``: :ref:`Concatenates variable number of\n arguments to one byte array`\n\n- ``string.concat(...) returns (string memory)``: :ref:`Concatenates variable number of\n arguments to one string array`\n\n.. index:: address;balance, address;codehash, address;send, address;code, address;transfer\n\nMembers of ``address``\n======================\n\n- ``
.balance`` (``uint256``): balance of the :ref:`address` in Wei\n- ``
.code`` (``bytes memory``): code at the :ref:`address` (can be empty)\n- ``
.codehash`` (``bytes32``): the codehash of the :ref:`address`\n- ``
.call(bytes memory) returns (bool, bytes memory)``: issue low-level ``CALL`` with the given payload,\n returns success condition and return data\n- ``
.delegatecall(bytes memory) returns (bool, bytes memory)``: issue low-level ``DELEGATECALL`` with the given payload,\n returns success condition and return data\n- ``
.staticcall(bytes memory) returns (bool, bytes memory)``: issue low-level ``STATICCALL`` with the given payload,\n returns success condition and return data\n- ``
.send(uint256 amount) returns (bool)``: send given amount of Wei to :ref:`address`,\n returns ``false`` on failure (deprecated)\n- ``
.transfer(uint256 amount)``: send given amount of Wei to :ref:`address`, throws on failure (deprecated)\n\n.. index:: blockhash, blobhash, block, block;basefee, block;blobbasefee, block;chainid, block;coinbase, block;difficulty, block;gaslimit, block;number, block;prevrandao, block;timestamp\n.. index:: gasleft, msg;data, msg;sender, msg;sig, msg;value, tx;gasprice, tx;origin\n\nBlock and Transaction Properties\n================================\n\n- ``blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks\n- ``blobhash(uint index) returns (bytes32)``: versioned hash of the ``index``-th blob associated with the current transaction.\n A versioned hash consists of a single byte representing the version (currently ``0x01``), followed by the last 31 bytes\n of the SHA256 hash of the KZG commitment (`EIP-4844 `_).\n Returns zero if no blob with the given index exists.\n- ``block.basefee`` (``uint``): current block's base fee (`EIP-3198 `_ and `EIP-1559 `_)\n- ``block.blobbasefee`` (``uint``): current block's blob base fee (`EIP-7516 `_ and `EIP-4844 `_)\n- ``block.chainid`` (``uint``): current chain id\n- ``block.coinbase`` (``address payable``): current block miner's address\n- ``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\n- ``block.gaslimit`` (``uint``): current block gaslimit\n- ``block.number`` (``uint``): current block number\n- ``block.prevrandao`` (``uint``): random number provided by the beacon chain (``EVM >= Paris``) (see `EIP-4399 `_ )\n- ``block.timestamp`` (``uint``): current block timestamp in seconds since Unix epoch\n- ``gasleft() returns (uint256)``: remaining gas\n- ``msg.data`` (``bytes``): complete calldata\n- ``msg.sender`` (``address``): sender of the message (current call)\n- ``msg.sig`` (``bytes4``): first four bytes of the calldata (i.e. function identifier)\n- ``msg.value`` (``uint``): number of wei sent with the message\n- ``tx.gasprice`` (``uint``): gas price of the transaction\n- ``tx.origin`` (``address``): sender of the transaction (full call chain)\n\n.. index:: assert, require, revert\n\nValidations and Assertions\n==========================\n\n- ``assert(bool condition)``: abort execution and revert state changes if condition is ``false`` (use for internal error)\n- ``require(bool condition)``: abort execution and revert state changes if condition is ``false`` (use\n for malformed input or error in external component)\n- ``require(bool condition, string memory message)``: abort execution and revert state changes if\n condition is ``false`` (use for malformed input or error in external component). Also provide error message.\n- ``revert()``: abort execution and revert state changes\n- ``revert(string memory message)``: abort execution and revert state changes providing an explanatory string\n\n.. index:: cryptography, keccak256, sha256, ripemd160, ecrecover, addmod, mulmod, erc7201\n\nMathematical and Cryptographic Functions\n========================================\n\n- ``keccak256(bytes memory) returns (bytes32)``: compute the Keccak-256 hash of the input\n- ``sha256(bytes memory) returns (bytes32)``: compute the SHA-256 hash of the input\n- ``ripemd160(bytes memory) returns (bytes20)``: compute the RIPEMD-160 hash of the input\n- ``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``: recover address associated with\n the public key from elliptic curve signature, return zero on error\n- ``addmod(uint x, uint y, uint k) returns (uint)``: compute ``(x + y) % k`` where the addition is performed with\n arbitrary precision and does not wrap around at ``2**256``. Assert that ``k != 0`` starting from version 0.5.0.\n- ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed\n with arbitrary precision and does not wrap around at ``2**256``. Assert that ``k != 0`` starting from version 0.5.0.\n- ``erc7201(string memory id) returns (uint)``: compute the base slot of an ``erc7201`` storage namespace.\n Can be used in compile time context.\n\n.. index:: this, super, selfdestruct\n\nContract-related\n================\n\n- ``this`` (current contract's type): the current contract, explicitly convertible to ``address`` or ``address payable``\n- ``super``: a contract one level higher in the inheritance hierarchy\n- ``selfdestruct(address payable recipient)``: send all funds to the given address and (only on EVMs before Cancun or when invoked within the transaction creating the contract) destroy the contract.\n\n.. index:: type;name, type;creationCode, type;runtimeCode, type;interfaceId, type;min, type;max\n\nType Information\n================\n\n- ``type(C).name`` (``string``): the name of the contract\n- ``type(C).creationCode`` (``bytes memory``): creation bytecode of the given contract, see :ref:`Type Information`.\n- ``type(C).runtimeCode`` (``bytes memory``): runtime bytecode of the given contract, see :ref:`Type Information`.\n- ``type(I).interfaceId`` (``bytes4``): value containing the EIP-165 interface identifier of the given interface, see :ref:`Type Information`.\n- ``type(T).min`` (``T``): the minimum value representable by the integer type ``T``, see :ref:`Type Information`.\n- ``type(T).max`` (``T``): the maximum value representable by the integer type ``T``, see :ref:`Type Information`.\n\n\n.. index:: visibility, public, private, external, internal\n\nFunction Visibility Specifiers\n==============================\n\n.. code-block:: solidity\n :force:\n\n function myFunction() returns (bool) {\n return true;\n }\n\n- ``public``: visible externally and internally (creates a :ref:`getter function` for storage/state variables)\n- ``private``: only visible in the current contract\n- ``external``: only visible externally (only for functions) - i.e. can only be message-called (via ``this.func``)\n- ``internal``: only visible internally\n\n\n.. index:: modifiers, pure, view, payable, constant, anonymous, indexed\n\nModifiers\n=========\n\n- ``pure`` for functions: Disallows modification or access of state.\n- ``view`` for functions: Disallows modification of state.\n- ``payable`` for functions: Allows them to receive Ether together with a call.\n- ``constant`` for state variables: Disallows assignment (except initialization), does not occupy storage slot.\n- ``immutable`` for state variables: Allows assignment at construction time and is constant when deployed. Is stored in code.\n- ``anonymous`` for events: Does not store event signature as topic.\n- ``indexed`` for event parameters: Stores the parameter as topic.\n- ``virtual`` for functions and modifiers: Allows the function's or modifier's\n behavior to be changed in derived contracts.\n- ``override``: States that this function, modifier or public state variable changes\n the behavior of a function or modifier in a base contract.\n\n" }, { "path": "docs/common-patterns.rst", "content": "###############\nCommon Patterns\n###############\n\n.. index:: withdrawal\n\n.. _withdrawal_pattern:\n\n*************************\nWithdrawal from Contracts\n*************************\n\nThe recommended method of sending funds after an effect\nis using the withdrawal pattern. Although the most intuitive\nmethod of sending Ether, as a result of an effect, is a\ndirect ``transfer`` call, this is not recommended as it\nintroduces a potential security risk. You may read\nmore about this on the :ref:`security_considerations` page.\n\nThe following is an example of the withdrawal pattern in practice in\na contract where the goal is to send the most of some compensation, e.g. Ether, to the\ncontract in order to become the \"richest\", inspired by\n`King of the Ether `_.\n\nIn the following contract, if you are no longer the richest,\nyou receive the funds of the person who is now the richest.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n\n contract WithdrawalContract {\n address public richest;\n uint public mostSent;\n\n mapping(address => uint) pendingWithdrawals;\n\n /// The amount of Ether sent was not higher than\n /// the currently highest amount.\n error NotEnoughEther();\n\n constructor() payable {\n richest = msg.sender;\n mostSent = msg.value;\n }\n\n function becomeRichest() public payable {\n if (msg.value <= mostSent) revert NotEnoughEther();\n pendingWithdrawals[richest] += msg.value;\n richest = msg.sender;\n mostSent = msg.value;\n }\n\n function withdraw() public {\n uint amount = pendingWithdrawals[msg.sender];\n // Remember to zero the pending refund before\n // sending to prevent reentrancy attacks\n pendingWithdrawals[msg.sender] = 0;\n (bool success, ) = payable(msg.sender).call{value: amount}(\"\");\n require(success);\n }\n }\n\nThis is as opposed to the more intuitive sending pattern:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n\n contract SendContract {\n address payable public richest;\n uint public mostSent;\n\n /// The amount of Ether sent was not higher than\n /// the currently highest amount.\n error NotEnoughEther();\n\n constructor() payable {\n richest = payable(msg.sender);\n mostSent = msg.value;\n }\n\n function becomeRichest() public payable {\n if (msg.value <= mostSent) revert NotEnoughEther();\n // This line can cause problems (explained below).\n (bool success, ) = richest.call{value: msg.value}(\"\");\n require(success);\n richest = payable(msg.sender);\n mostSent = msg.value;\n }\n }\n\nNotice that, in this example, an attacker could trap the\ncontract into an unusable state by causing ``richest`` to be\nthe address of a contract that has a receive or fallback function\nwhich fails (e.g. by using ``revert()`` or by just\nconsuming more than the 2300 gas stipend transferred to them). That way,\nwhenever ``transfer`` is called to deliver funds to the\n\"poisoned\" contract, it will fail and thus also ``becomeRichest``\nwill fail, with the contract being stuck forever.\n\nIn contrast, if you use the \"withdraw\" pattern from the first example,\nthe attacker can only cause his or her own withdraw to fail and not the\nrest of the contract's workings.\n\n.. index:: access;restricting\n\n******************\nRestricting Access\n******************\n\nRestricting access is a common pattern for contracts.\nNote that you can never restrict any human or computer\nfrom reading the content of your transactions or\nyour contract's state. You can make it a bit harder\nby using encryption, but if your contract is supposed\nto read the data, so will everyone else.\n\nYou can restrict read access to your contract's state\nby **other contracts**. That is actually the default\nunless you declare your state variables ``public``.\n\nFurthermore, you can restrict who can make modifications\nto your contract's state or call your contract's\nfunctions and this is what this section is about.\n\n.. index:: function;modifier\n\nThe use of **function modifiers** makes these\nrestrictions highly readable.\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n\n contract AccessRestriction {\n // These will be assigned at the construction\n // phase, where `msg.sender` is the account\n // creating this contract.\n address public owner = msg.sender;\n uint public creationTime = block.timestamp;\n\n // Now follows a list of errors that\n // this contract can generate together\n // with a textual explanation in special\n // comments.\n\n /// Sender not authorized for this\n /// operation.\n error Unauthorized();\n\n /// Function called too early.\n error TooEarly();\n\n /// Not enough Ether sent with function call.\n error NotEnoughEther();\n\n // Modifiers can be used to change\n // the body of a function.\n // If this modifier is used, it will\n // prepend a check that only passes\n // if the function is called from\n // a certain address.\n modifier onlyBy(address account)\n {\n if (msg.sender != account)\n revert Unauthorized();\n // Do not forget the \"_;\"! It will\n // be replaced by the actual function\n // body when the modifier is used.\n _;\n }\n\n /// Make `newOwner` the new owner of this\n /// contract.\n function changeOwner(address newOwner)\n public\n onlyBy(owner)\n {\n owner = newOwner;\n }\n\n modifier onlyAfter(uint time) {\n if (block.timestamp < time)\n revert TooEarly();\n _;\n }\n\n /// Erase ownership information.\n /// May only be called 6 weeks after\n /// the contract has been created.\n function disown()\n public\n onlyBy(owner)\n onlyAfter(creationTime + 6 weeks)\n {\n delete owner;\n }\n\n // This modifier requires a certain\n // fee being associated with a function call.\n // If the caller sent too much, he or she is\n // refunded, but only after the function body.\n // This was dangerous before Solidity version 0.4.0,\n // where it was possible to skip the part after `_;`.\n modifier costs(uint amount) {\n if (msg.value < amount)\n revert NotEnoughEther();\n\n _;\n if (msg.value > amount) {\n (bool success, ) = payable(msg.sender).call{value: msg.value - amount}(\"\");\n require(success);\n }\n }\n\n function forceOwnerChange(address newOwner)\n public\n payable\n costs(200 ether)\n {\n owner = newOwner;\n // just some example condition\n if (uint160(owner) & 0 == 1)\n // This did not refund for Solidity\n // before version 0.4.0.\n return;\n // refund overpaid fees\n }\n }\n\nA more specialised way in which access to function\ncalls can be restricted will be discussed\nin the next example.\n\n.. index:: state machine\n\n*************\nState Machine\n*************\n\nContracts often act as a state machine, which means\nthat they have certain **stages** in which they behave\ndifferently or in which different functions can\nbe called. A function call often ends a stage\nand transitions the contract into the next stage\n(especially if the contract models **interaction**).\nIt is also common that some stages are automatically\nreached at a certain point in **time**.\n\nAn example for this is a blind auction contract which\nstarts in the stage \"accepting blinded bids\", then\ntransitions to \"revealing bids\" which is ended by\n\"determine auction outcome\".\n\n.. index:: function;modifier\n\nFunction modifiers can be used in this situation\nto model the states and guard against\nincorrect usage of the contract.\n\nExample\n=======\n\nIn the following example,\nthe modifier ``atStage`` ensures that the function can\nonly be called at a certain stage.\n\nAutomatic timed transitions\nare handled by the modifier ``timedTransitions``, which\nshould be used for all functions.\n\n.. note::\n **Modifier Order Matters**.\n If atStage is combined\n with timedTransitions, make sure that you mention\n it after the latter, so that the new stage is\n taken into account.\n\nFinally, the modifier ``transitionNext`` can be used\nto automatically go to the next stage when the\nfunction finishes.\n\n.. note::\n **Modifier May be Skipped**.\n This only applies to Solidity before version 0.4.0:\n Since modifiers are applied by simply replacing\n code and not by using a function call,\n the code in the transitionNext modifier\n can be skipped if the function itself uses\n return. If you want to do that, make sure\n to call nextStage manually from those functions.\n Starting with version 0.4.0, modifier code\n will run even if the function explicitly returns.\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n\n contract StateMachine {\n enum Stages {\n AcceptingBlindedBids,\n RevealBids,\n AnotherStage,\n AreWeDoneYet,\n Finished\n }\n /// Function cannot be called at this time.\n error FunctionInvalidAtThisStage();\n\n // This is the current stage.\n Stages public stage = Stages.AcceptingBlindedBids;\n\n uint public creationTime = block.timestamp;\n\n modifier atStage(Stages stage_) {\n if (stage != stage_)\n revert FunctionInvalidAtThisStage();\n _;\n }\n\n function nextStage() internal {\n stage = Stages(uint(stage) + 1);\n }\n\n // Perform timed transitions. Be sure to mention\n // this modifier first, otherwise the guards\n // will not take the new stage into account.\n modifier timedTransitions() {\n if (stage == Stages.AcceptingBlindedBids &&\n block.timestamp >= creationTime + 10 days)\n nextStage();\n if (stage == Stages.RevealBids &&\n block.timestamp >= creationTime + 12 days)\n nextStage();\n // The other stages transition by transaction\n _;\n }\n\n // Order of the modifiers matters here!\n function bid()\n public\n payable\n timedTransitions\n atStage(Stages.AcceptingBlindedBids)\n {\n // We will not implement that here\n }\n\n function reveal()\n public\n timedTransitions\n atStage(Stages.RevealBids)\n {\n }\n\n // This modifier goes to the next stage\n // after the function is done.\n modifier transitionNext()\n {\n _;\n nextStage();\n }\n\n function g()\n public\n timedTransitions\n atStage(Stages.AnotherStage)\n transitionNext\n {\n }\n\n function h()\n public\n timedTransitions\n atStage(Stages.AreWeDoneYet)\n transitionNext\n {\n }\n\n function i()\n public\n timedTransitions\n atStage(Stages.Finished)\n {\n }\n }\n" }, { "path": "docs/conf.py", "content": "#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n#\n# Solidity documentation build configuration file, created by\n# sphinx-quickstart on Mon Dec 7 12:32:57 2015.\n#\n# This file is execfile()d with the current directory set to its\n# containing dir.\n#\n# Note that not all possible configuration values are present in this\n# autogenerated file.\n#\n# All configuration values have a default; values that are commented out\n# serve to show the default.\n\nimport sys\nimport os\nimport re\n\nfrom pygments_lexer_solidity import SolidityLexer, YulLexer\n\n# If extensions (or modules to document with autodoc) are in another directory,\n# add these directories to sys.path here. If the directory is relative to the\n# documentation root, use os.path.abspath to make it absolute, like shown here.\n\nROOT_PATH = os.path.dirname(os.path.realpath(__file__))\n\nsys.path.insert(0, os.path.join(ROOT_PATH, 'ext'))\n\ndef setup(sphinx):\n sphinx.add_lexer('Solidity', SolidityLexer)\n sphinx.add_lexer('Yul', YulLexer)\n\n sphinx.add_css_file('css/fonts.css')\n sphinx.add_css_file('css/custom.css')\n sphinx.add_css_file('css/custom-dark.css')\n sphinx.add_css_file('css/pygments.css')\n\n# -- RTD GitHub configuration ---------------------------------------------\n\n# Taken from:\n# https://github.com/readthedocs/readthedocs.org/blob/e366e7fc8649fbcf1b6d06ecc12c5f7766144c46/readthedocs/projects/constants.py#L350\nGITHUB_REGEXS = [\n re.compile(r\"github.com/(.+)/(.+)(?:\\.git){1}$\"),\n # This must come before the one without a / to make sure we don't capture the /\n re.compile(r\"github.com/(.+)/(.+)/\"),\n re.compile(r\"github.com/(.+)/(.+)\"),\n re.compile(r\"github.com:(.+)/(.+)\\.git$\"),\n]\n\n# Taken and adapted from:\n# https://github.com/readthedocs/readthedocs.org/blob/e366e7fc8649fbcf1b6d06ecc12c5f7766144c46/readthedocs/builds/utils.py#L24\ndef get_github_username_repo(url):\n if \"github\" in url:\n for regex in GITHUB_REGEXS:\n match = regex.search(url)\n if match:\n return match.groups()\n return (None, None)\n\ndisplay_github = False\n# NOTE: RTD_DISPLAY_GITHUB, RTD_GITHUB_USER and RTD_GITHUB_REPO are set in the RTD project settings\ngithub_user = os.getenv(\"RTD_GITHUB_USER\")\ngithub_repo = os.getenv(\"RTD_GITHUB_REPO\")\n\nif github_user and github_repo:\n display_github = True\nelse:\n git_clone_url = os.getenv(\"READTHEDOCS_GIT_CLONE_URL\")\n if git_clone_url:\n github_user, github_repo = get_github_username_repo(git_clone_url)\n if github_user and github_repo:\n display_github = True\n\ndisplay_github_env = os.getenv(\"RTD_DISPLAY_GITHUB\")\nif display_github_env:\n display_github = display_github_env.lower() == \"true\"\n\nhtml_context = {\n \"display_github\": display_github,\n \"github_user\": github_user,\n \"github_repo\": github_repo,\n \"github_version\": os.getenv(\"READTHEDOCS_VERSION\", \"develop\"),\n \"conf_py_path\": \"/docs/\",\n}\n\n# -- General configuration ------------------------------------------------\n# If your documentation needs a minimal Sphinx version, state it here.\n#needs_sphinx = '1.0'\n\n# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n# ones.\nextensions = [\n 'sphinx_syntax',\n 'html_extra_template_renderer',\n 'remix_code_links',\n 'sphinx.ext.imgconverter',\n]\n\nsyntax_base_path = 'grammar'\n# generate link anchors compatible with Sphinx-A4Doc’s naming\nsyntax_a4doc_compat_links = True\n\n# Add any paths that contain templates here, relative to this directory.\ntemplates_path = ['_templates']\n\n# The suffix of source filenames.\nsource_suffix = '.rst'\n\n# The encoding of source files.\n#source_encoding = 'utf-8-sig'\n\n# The master toctree document.\nmaster_doc = 'index'\n\n# General information about the project.\nproject = 'Solidity'\nproject_copyright = '2016-2025, The Solidity Authors'\n\n# The version info for the project you're documenting, acts as replacement for\n# |version| and |release|, also used in various other places throughout the\n# built documents.\n#\n# The short X.Y version.\nwith open('../CMakeLists.txt', 'r', encoding='utf8') as f:\n version = re.search('PROJECT_VERSION \"([^\"]+)\"', f.read()).group(1)\n# The full version, including alpha/beta/rc tags.\nif os.path.isfile('../prerelease.txt') and os.path.getsize('../prerelease.txt') == 0:\n release = version\nelif os.path.isfile('../prerelease.txt'):\n with open('../prerelease.txt', 'r', encoding='utf8') as prerelease_file:\n release = version + '-' + prerelease_file.read()\nelse:\n release = version + '-develop'\n\n# The language for content autogenerated by Sphinx. Refer to documentation\n# for a list of supported languages.\n#language = None\n\n# There are two options for replacing |today|: either, you set today to some\n# non-false value, then it is used:\n#today = ''\n# Else, today_fmt is used as the format for a strftime call.\n#today_fmt = '%B %d, %Y'\n\n# List of patterns, relative to source directory, that match files and\n# directories to ignore when looking for source files.\nexclude_patterns = ['_build', 'contracts', 'types', 'examples', 'grammar']\n\n# The reST default role (used for this markup: `text`) to use for all\n# documents.\n#default_role = None\n\n# If true, '()' will be appended to :func: etc. cross-reference text.\n#add_function_parentheses = True\n\n# If true, the current module name will be prepended to all description\n# unit titles (such as .. function::).\n#add_module_names = True\n\n# If true, sectionauthor and moduleauthor directives will be shown in the\n# output. They are ignored by default.\n#show_authors = False\n\n# The name of the Pygments (syntax highlighting) style to use.\npygments_style = 'sphinx'\n\nhighlight_language = 'Solidity'\n\n# A list of ignored prefixes for module index sorting.\n#modindex_common_prefix = []\n\n# If true, keep warnings as \"system message\" paragraphs in the built documents.\n#keep_warnings = False\n\nsuppress_warnings = [\n # Suppress sphinx-syntax warnings, in particular `diagram descriptions can't have custom resolver_data`\n 'sphinx_syntax',\n]\n\n# -- Options for HTML output ----------------------------------------------\n\n# The theme to use for HTML and HTML Help pages. See the documentation for\n# a list of builtin themes.\nhtml_theme = 'sphinx_rtd_theme'\n\n# Theme options are theme-specific and customize the look and feel of a theme\n# further. For a list of options available for each theme, see the\n# documentation.\nhtml_theme_options = {\n 'logo_only': True,\n 'version_selector': True,\n 'language_selector': True,\n}\n\n# Add any paths that contain custom themes here, relative to this directory.\n#html_theme_path = []\n\n# The name for this set of Sphinx documents. If None, it defaults to\n# \" v documentation\".\n#html_title = None\n\n# A shorter title for the navigation bar. Default is the same as html_title.\n#html_short_title = None\n\n# The name of an image file (relative to this directory) to place at the top\n# of the sidebar.\n# html_logo = \"logo.svg\"\n\n# The name of an image file (within the static path) to use as favicon of the\n# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32\n# pixels large.\nhtml_favicon = \"_static/img/favicon.ico\"\n\n# Add any paths that contain custom static files (such as style sheets) here,\n# relative to this directory. They are copied after the builtin static files,\n# so a file named \"default.css\" will overwrite the builtin \"default.css\".\nhtml_static_path = ['_static']\n\nhtml_css_files = [\"css/toggle.css\"]\n\nhtml_js_files = [\"js/constants.js\", \"js/initialize.js\", \"js/toggle.js\"]\n\n# Add any extra paths that contain custom files (such as robots.txt or\n# .htaccess) here, relative to this directory. These files are copied\n# directly to the root of the documentation.\nhtml_extra_path = [\"_static/css\"]\n\n# List of templates of static files to be included in the HTML output.\n# Keys represent paths to input files and values are dicts containing:\n# - target: The path where the rendered template should be placed.\n# - context: A dictionary listing variables that can be used inside the template.\n# All paths must be absolute.\n# Rendered templates are automatically added to html_extra_path setting.\nhtml_extra_templates = {\n os.path.join(ROOT_PATH, \"robots.txt.template\"): {\n 'target': os.path.join(ROOT_PATH, \"_static/robots.txt\"),\n 'context': {'LATEST_VERSION': version},\n }\n}\n\n# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,\n# using the given strftime format.\n#html_last_updated_fmt = '%b %d, %Y'\n\n# If true, SmartyPants will be used to convert quotes and dashes to\n# typographically correct entities.\n#html_use_smartypants = True\n\n# Custom sidebar templates, maps document names to template names.\n#html_sidebars = {}\n\n# Additional templates that should be rendered to pages, maps page names to\n# template names.\n#html_additional_pages = {}\n\n# If false, no module index is generated.\n#html_domain_indices = True\n\n# If false, no index is generated.\n#html_use_index = True\n\n# If true, the index is split into individual pages for each letter.\n#html_split_index = False\n\n# If true, links to the reST sources are added to the pages.\n#html_show_sourcelink = True\n\n# If true, \"Created using Sphinx\" is shown in the HTML footer. Default is True.\nhtml_show_sphinx = False\n\n# If true, \"(C) Copyright ...\" is shown in the HTML footer. Default is True.\n#html_show_copyright = True\n\n# If true, an OpenSearch description file will be output, and all pages will\n# contain a tag referring to it. The value of this option must be the\n# base URL from which the finished HTML is served.\n#html_use_opensearch = ''\n\n# This is the file name suffix for HTML files (e.g. \".xhtml\").\n#html_file_suffix = None\n\n# Output file base name for HTML help builder.\nhtmlhelp_basename = 'Soliditydoc'\n\n\n# -- Options for LaTeX output ---------------------------------------------\n\nlatex_elements = {\n# The paper size ('letterpaper' or 'a4paper').\n#'papersize': 'letterpaper',\n\n# The font size ('10pt', '11pt' or '12pt').\n#'pointsize': '10pt',\n\n# Additional stuff for the LaTeX preamble.\n#'preamble': '',\n}\n\n# Grouping the document tree into LaTeX files. List of tuples\n# (source start file, target name, title,\n# author, documentclass [howto, manual, or own class]).\nlatex_documents = [\n ('index', 'solidity.tex', 'Solidity Documentation', 'Ethereum', 'manual'),\n]\n\n# The name of an image file (relative to this directory) to place at the top of\n# the title page.\n#latex_logo = None\n\n# For \"manual\" documents, if this is true, then toplevel headings are parts,\n# not chapters.\n#latex_use_parts = False\n\n# If true, show page references after internal links.\n#latex_show_pagerefs = False\n\n# If true, show URL addresses after external links.\n#latex_show_urls = False\n\n# Documents to append as an appendix to all manuals.\n#latex_appendices = []\n\n# If false, no module index is generated.\n#latex_domain_indices = True\n\n\n# -- Options for manual page output ---------------------------------------\n\n# One entry per manual page. List of tuples\n# (source start file, name, description, authors, manual section).\nman_pages = [\n]\n\n# If true, show URL addresses after external links.\n#man_show_urls = False\n\n\n# -- Options for Texinfo output -------------------------------------------\n\n# Grouping the document tree into Texinfo files. List of tuples\n# (source start file, target name, title, author,\n# dir menu entry, description, category)\ntexinfo_documents = [\n]\n\n# Documents to append as an appendix to all manuals.\n#texinfo_appendices = []\n\n# If false, no module index is generated.\n#texinfo_domain_indices = True\n\n# How to display URL addresses: 'footnote', 'no', or 'inline'.\n#texinfo_show_urls = 'footnote'\n\n# If true, do not generate a @detailmenu in the \"Top\" node's menu.\n#texinfo_no_detailmenu = False\n" }, { "path": "docs/contracts/abstract-contracts.rst", "content": ".. index:: ! contract;abstract, ! abstract contract\n\n.. _abstract-contract:\n\n******************\nAbstract Contracts\n******************\n\nContracts must be marked as abstract when at least one of their functions is not implemented or when\nthey do not provide arguments for all of their base contract constructors.\nEven if this is not the case, a contract may still be marked abstract, such as when you do not intend\nfor the contract to be created directly. Abstract contracts are similar to :ref:`interfaces` but an\ninterface is more limited in what it can declare.\n\nAn abstract contract is declared using the ``abstract`` keyword as shown in the following example.\nNote that this contract needs to be defined as abstract, because the function ``utterance()`` is declared,\nbut no implementation was provided (no implementation body ``{ }`` was given).\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n abstract contract Feline {\n function utterance() public virtual returns (bytes32);\n }\n\nSuch abstract contracts can not be instantiated directly. This is also true, if an abstract contract itself does implement\nall defined functions. The usage of an abstract contract as a base class is shown in the following example:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n abstract contract Feline {\n function utterance() public pure virtual returns (bytes32);\n }\n\n contract Cat is Feline {\n function utterance() public pure override returns (bytes32) { return \"miaow\"; }\n }\n\nIf a contract inherits from an abstract contract and does not implement all non-implemented\nfunctions by overriding, it needs to be marked as abstract as well.\n\nNote that a function without implementation is different from\na :ref:`Function Type ` even though their syntax looks very similar.\n\nExample of function without implementation (a function declaration):\n\n.. code-block:: solidity\n\n function foo(address) external returns (address);\n\nExample of a declaration of a variable whose type is a function type:\n\n.. code-block:: solidity\n\n function(address) external returns (address) foo;\n\nAbstract contracts decouple the definition of a contract from its\nimplementation providing better extensibility and self-documentation and\nfacilitating patterns like the `Template method `_ and removing code duplication.\nAbstract contracts are useful in the same way that defining methods\nin an interface is useful. It is a way for the designer of the\nabstract contract to say \"any child of mine must implement this method\".\n\n.. note::\n\n Abstract contracts cannot override an implemented virtual function with an\n unimplemented one.\n" }, { "path": "docs/contracts/constant-state-variables.rst", "content": ".. index:: ! constant\n\n.. _constants:\n\n**************************************\nConstant and Immutable State Variables\n**************************************\n\nState variables can be declared as ``constant`` or ``immutable``.\nIn both cases, the variables cannot be modified after the contract has been constructed.\nFor ``constant`` variables, the value has to be fixed at compile-time, while\nfor ``immutable``, it can still be assigned at construction time.\n\nIt is also possible to define ``constant`` variables at the file level.\n\nEvery occurrence of such a variable in the source is replaced by its underlying value\nand the compiler does not reserve a storage slot for it.\nIt cannot be assigned a slot in transient storage using the ``transient`` keyword either.\n\nCompared to regular state variables, the gas costs of constant and immutable variables\nare much lower. For a constant variable, the expression assigned to it is copied to\nall the places where it is accessed and also re-evaluated each time. This allows for local\noptimizations. Immutable variables are evaluated once at construction time and their value\nis copied to all the places in the code where they are accessed. For these values,\n32 bytes are reserved, even if they would fit in fewer bytes. Due to this, constant values\ncan sometimes be cheaper than immutable values.\n\nNot all types for constants and immutables are implemented at this time. The only supported types are\n:ref:`strings ` (only for constants) and :ref:`value types `.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.21;\n\n uint constant X = 32**22 + 8;\n\n contract C {\n string constant TEXT = \"abc\";\n bytes32 constant MY_HASH = keccak256(\"abc\");\n uint immutable decimals = 18;\n uint immutable maxBalance;\n address immutable owner = msg.sender;\n\n constructor(uint decimals_, address ref) {\n if (decimals_ != 0)\n // Immutables are only immutable when deployed.\n // At construction time they can be assigned to any number of times.\n decimals = decimals_;\n\n // Assignments to immutables can even access the environment.\n maxBalance = ref.balance;\n }\n\n function isBalanceTooHigh(address other) public view returns (bool) {\n return other.balance > maxBalance;\n }\n }\n\n\nConstant\n========\n\nFor ``constant`` variables, the value has to be a constant at compile time and it has to be\nassigned where the variable is declared. Any expression\nthat accesses storage, blockchain data (e.g. ``block.timestamp``, ``address(this).balance`` or\n``block.number``) or\nexecution data (``msg.value`` or ``gasleft()``) or makes calls to external contracts is disallowed. Expressions\nthat might have a side-effect on memory allocation are allowed, but those that\nmight have a side-effect on other memory objects are not. The built-in functions\n``keccak256``, ``sha256``, ``ripemd160``, ``ecrecover``, ``addmod`` and ``mulmod``\nare allowed (even though, with the exception of ``keccak256``, they do call external contracts).\n\nThe reason behind allowing side-effects on the memory allocator is that it\nshould be possible to construct complex objects like e.g. lookup-tables.\nThis feature is not yet fully usable.\n\nImmutable\n=========\n\nVariables declared as ``immutable`` are a bit less restricted than those\ndeclared as ``constant``: Immutable variables can be assigned a\nvalue at construction time.\nThe value can be changed at any time before deployment and then it becomes permanent.\n\nOne additional restriction is that immutables can only be assigned to inside expressions for which\nthere is no possibility of being executed after creation.\nThis excludes all modifier definitions and functions other than constructors.\n\nThere are no restrictions on reading immutable variables.\nThe read is even allowed to happen before the variable is written to for the first time because variables in\nSolidity always have a well-defined initial value.\nFor this reason it is also allowed to never explicitly assign a value to an immutable.\n\n.. warning::\n When accessing immutables at construction time, please keep the :ref:`initialization order\n ` in mind.\n Even if you provide an explicit initializer, some expressions may end up being evaluated before\n that initializer, especially when they are at a different level in inheritance hierarchy.\n\n.. note::\n Before Solidity 0.8.21 initialization of immutable variables was more restrictive.\n Such variables had to be initialized exactly once at construction time and could not be read\n before then.\n\nThe contract creation code generated by the compiler will modify the\ncontract's runtime code before it is returned by replacing all references\nto immutables with the values assigned to them. This is important if\nyou are comparing the\nruntime code generated by the compiler with the one actually stored in the\nblockchain. The compiler outputs where these immutables are located in the deployed bytecode\nin the ``immutableReferences`` field of the :ref:`compiler JSON standard output `.\n" }, { "path": "docs/contracts/creating-contracts.rst", "content": ".. index:: ! contract;creation, constructor\n\n******************\nCreating Contracts\n******************\n\nContracts can be created \"from outside\" via Ethereum transactions or from within Solidity contracts.\n\nIDEs, such as `Remix `_, make the creation process seamless using UI elements.\n\nOne way to create contracts programmatically on Ethereum is via the JavaScript API `web3.js `_.\nIt has a function called `web3.eth.Contract `_\nto facilitate contract creation.\n\nWhen a contract is created, its :ref:`constructor ` (a function declared with\nthe ``constructor`` keyword) is executed once.\n\nA constructor is optional. Only one constructor is allowed, which means\noverloading is not supported.\n\nAfter the constructor has executed, the final code of the contract is stored on the\nblockchain. This code includes all public and external functions and all functions\nthat are reachable from there through function calls. The deployed code does not\ninclude the constructor code or internal functions only called from the constructor.\n\n.. index:: constructor;arguments\n\nInternally, constructor arguments are passed :ref:`ABI encoded ` after the code of\nthe contract itself, but you do not have to care about this if you use ``web3.js``.\n\nIf a contract wants to create another contract, the source code\n(and the binary) of the created contract has to be known to the creator.\nThis means that cyclic creation dependencies are impossible.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.22 <0.9.0;\n\n\n contract OwnedToken {\n // `TokenCreator` is a contract type that is defined below.\n // It is fine to reference it as long as it is not used\n // to create a new contract.\n TokenCreator creator;\n address owner;\n bytes32 name;\n\n // This is the constructor which registers the\n // creator and the assigned name.\n constructor(bytes32 name_) {\n // State variables are accessed via their name\n // and not via e.g. `this.owner`. Functions can\n // be accessed directly or through `this.f`,\n // but the latter provides an external view\n // to the function. Especially in the constructor,\n // you should not access functions externally,\n // because the function does not exist yet.\n // See the next section for details.\n owner = msg.sender;\n\n // We perform an explicit type conversion from `address`\n // to `TokenCreator` and assume that the type of\n // the calling contract is `TokenCreator`, there is\n // no real way to verify that.\n // This does not create a new contract.\n creator = TokenCreator(msg.sender);\n name = name_;\n }\n\n function changeName(bytes32 newName) public {\n // Only the creator can alter the name.\n // We compare the contract based on its\n // address which can be retrieved by\n // explicit conversion to address.\n if (msg.sender == address(creator))\n name = newName;\n }\n\n function transfer(address newOwner) public {\n // Only the current owner can transfer the token.\n if (msg.sender != owner) return;\n\n // We ask the creator contract if the transfer\n // should proceed by using a function of the\n // `TokenCreator` contract defined below. If\n // the call fails (e.g. due to out-of-gas),\n // the execution also fails here.\n if (creator.isTokenTransferOK(owner, newOwner))\n owner = newOwner;\n }\n }\n\n\n contract TokenCreator {\n function createToken(bytes32 name)\n public\n returns (OwnedToken tokenAddress)\n {\n // Create a new `Token` contract and return its address.\n // From the JavaScript side, the return type\n // of this function is `address`, as this is\n // the closest type available in the ABI.\n return new OwnedToken(name);\n }\n\n function changeName(OwnedToken tokenAddress, bytes32 name) public {\n // Again, the external type of `tokenAddress` is\n // simply `address`.\n tokenAddress.changeName(name);\n }\n\n // Perform checks to determine if transferring a token to the\n // `OwnedToken` contract should proceed\n function isTokenTransferOK(address currentOwner, address newOwner)\n public\n pure\n returns (bool ok)\n {\n // Check an arbitrary condition to see if transfer should proceed\n return keccak256(abi.encodePacked(currentOwner, newOwner))[0] == 0x7f;\n }\n }\n" }, { "path": "docs/contracts/custom-storage-layout.rst", "content": ".. index:: ! custom storage layout, ! storage layout specifier, ! layout at, ! base slot\n\n.. _custom-storage-layout:\n\n*********************\nCustom Storage Layout\n*********************\n\nA contract can define an arbitrary location for its storage using the ``layout`` specifier.\nThe contract's state variables, including those inherited from base contracts,\nstart from the specified base slot instead of the default slot zero.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.29;\n\n contract C layout at 0xAAAA + 0x11 {\n uint[3] x; // Occupies slots 0xAABB..0xAABD\n }\n\nAs the above example shows, the specifier uses the ``layout at `` syntax\nand is located in the header of a contract definition.\n\nThe layout specifier can be placed either before or after the inheritance specifier, and can appear at most once.\nThe ``base-slot-expression`` must be an :ref:`integer literal` expression\nthat can be evaluated at compilation time and yields a value in the range of ``uint256``.\nThe use of constants initialized using such expressions and\nthe :ref:`built-in function erc7201` is also allowed.\n\nA custom layout cannot make contract's storage \"wrap around\".\nIf the selected base slot would push the static variables past the end of storage,\nthe compiler will issue an error.\nNote that the data areas of dynamic arrays and mappings are not affected by this check because\ntheir layout is not linear.\nRegardless of the base slot used, their locations are calculated in a way that always puts them\nwithin the range of ``uint256`` and their sizes are not known at compilation time.\n\nWhile there are no other limits placed on the base slot, it is recommended to avoid locations that are\ntoo close to the end of the address space.\nLeaving too little space may complicate contract upgrades or cause problems for contracts that store\nadditional values past their allocated space using inline assembly.\n\nThe storage layout can only be specified for the topmost contract of an inheritance tree, and\naffects locations of all the storage variables in all the contracts in that tree.\nVariables are laid out according to the order of their definitions and the\npositions of their contracts in the :ref:`linearized inheritance hierarchy`\nand a custom base slot preserves their relative positions, shifting them all by the same amount.\n\nThe storage layout cannot be specified for abstract contracts, interfaces and libraries.\nAlso, it is important to note that it does *not* affect transient state variables.\n\nFor details about storage layout and the effect of the layout specifier on it see\n:ref:`layout of storage variables`.\n\n.. warning::\n The identifiers ``layout`` and ``at`` are not yet reserved as keywords in the language.\n It is strongly recommended to avoid using them since they will become reserved in a future\n breaking release.\n" }, { "path": "docs/contracts/errors.rst", "content": ".. index:: ! error, revert, require, ! selector; of an error\n.. _errors:\n\n*************\nCustom Errors\n*************\n\nErrors in Solidity provide a convenient and gas-efficient way to explain to the\nuser why an operation failed. They can be defined inside and outside of contracts (including interfaces and libraries).\n\nThey have to be used together with the :ref:`revert statement `\nor the :ref:`require function `.\nIn the case of ``revert`` statements, or ``require`` calls where the condition is evaluated to be false,\nall changes in the current call are reverted, and the error data passed back to the caller.\n\nThe example below shows custom error usage with the ``revert`` statement in function ``transferWithRevertError``,\nas well as the newer approach with ``require`` in function ``transferWithRequireError``.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.27;\n\n /// Insufficient balance for transfer. Needed `required` but only\n /// `available` available.\n /// @param available balance available.\n /// @param required requested amount to transfer.\n error InsufficientBalance(uint256 available, uint256 required);\n\n contract TestToken {\n mapping(address => uint) balance;\n function transferWithRevertError(address to, uint256 amount) public {\n if (amount > balance[msg.sender])\n revert InsufficientBalance({\n available: balance[msg.sender],\n required: amount\n });\n balance[msg.sender] -= amount;\n balance[to] += amount;\n }\n function transferWithRequireError(address to, uint256 amount) public {\n require(amount <= balance[msg.sender], InsufficientBalance(balance[msg.sender], amount));\n balance[msg.sender] -= amount;\n balance[to] += amount;\n }\n // ...\n }\n\nAnother important detail to mention when it comes to using ``require`` with custom errors, is that memory\nallocation for the error-based revert reason will only happen in the reverting case, which, along with\noptimization of constants and string literals makes this about as gas-efficient as the\n``if (!condition) revert CustomError(args)`` pattern.\n\nErrors cannot be overloaded or overridden but are inherited.\nThe same error can be defined in multiple places as long as the scopes are distinct.\nInstances of errors can only be created using ``revert`` statements, or as the second argument to ``require`` functions.\n\nThe error creates data that is then passed to the caller with the revert operation\nto either return to the off-chain component or catch it in a :ref:`try/catch statement `.\nNote that an error can only be caught when coming from an external call,\nreverts happening in internal calls or inside the same function cannot be caught.\n\nIf you do not provide any parameters, the error only needs four bytes of\ndata and you can use :ref:`NatSpec ` as above\nto further explain the reasons behind the error, which is not stored on chain.\nThis makes this a very cheap and convenient error-reporting feature at the same time.\n\nMore specifically, an error instance is ABI-encoded in the same way as\na function call to a function of the same name and types would be\nand then used as the return data in the ``revert`` opcode.\nThis means that the data consists of a 4-byte selector followed by :ref:`ABI-encoded` data.\nThe selector consists of the first four bytes of the keccak256-hash of the signature of the error type.\n\n.. note::\n It is possible for a contract to revert\n with different errors of the same name or even with errors defined in different places\n that are indistinguishable by the caller. For the outside, i.e. the ABI,\n only the name of the error is relevant, not the contract or file where it is defined.\n\nThe statement ``require(condition, \"description\");`` would be equivalent to\n``if (!condition) revert Error(\"description\")`` if you could define ``error Error(string)``.\nNote, however, that ``Error`` is a built-in type and cannot be defined in user-supplied code.\n\nSimilarly, a failing ``assert`` or similar conditions will revert with an error\nof the built-in type ``Panic(uint256)``.\n\n.. note::\n Error data should only be used to give an indication of failure, but\n not as a means for control-flow. The reason is that the revert data\n of inner calls is propagated back through the chain of external calls\n by default. This means that an inner call\n can \"forge\" revert data that looks like it could have come from the\n contract that called it.\n\nMembers of Errors\n=================\n\n- ``error.selector``: A ``bytes4`` value containing the error selector.\n" }, { "path": "docs/contracts/events.rst", "content": ".. index:: ! event, ! event; anonymous, ! event; indexed, ! event; topic\n\n.. _events:\n\n******\nEvents\n******\n\nSolidity events give an abstraction on top of the EVM's logging functionality.\nApplications can subscribe and listen to these events through the RPC interface of an Ethereum client.\n\nEvents can be defined at file level or as inheritable members of contracts (including interfaces and libraries).\nWhen you call them, they cause the\narguments to be stored in the transaction's log - a special data structure\nin the blockchain. These logs are associated with the address of the contract that emitted them,\nare incorporated into the blockchain, and stay there as long as a block is\naccessible (forever as of now, but this might\nchange in the future). The Log and its event data are not accessible from within\ncontracts (not even from the contract that created them).\n\nIt is possible to request a Merkle proof for logs, so if\nan external entity supplies a contract with such a proof, it can check\nthat the log actually exists inside the blockchain. You have to supply block headers\nbecause the contract can only see the last 256 block hashes.\n\nYou can add the attribute ``indexed`` to up to three parameters which adds them\nto a special data structure known as :ref:`\"topics\" ` instead of\nthe data part of the log.\nA topic can only hold a single word (32 bytes) so if you use a :ref:`reference type\n` for an indexed argument, the Keccak-256 hash of the value is stored\nas a topic instead.\n\nAll parameters without the ``indexed`` attribute are :ref:`ABI-encoded `\ninto the data part of the log.\n\nTopics allow you to search for events, for example when filtering a sequence of\nblocks for certain events. You can also filter events by the address of the\ncontract that emitted the event.\n\nFor example, the code below uses the web3.js ``subscribe(\"logs\")``\n`method `_ to filter\nlogs that match a topic with a certain address value:\n\n.. code-block:: javascript\n\n var options = {\n fromBlock: 0,\n address: web3.eth.defaultAccount,\n topics: [\"0x0000000000000000000000000000000000000000000000000000000000000000\", null, null]\n };\n web3.eth.subscribe('logs', options, function (error, result) {\n if (!error)\n console.log(result);\n })\n .on(\"data\", function (log) {\n console.log(log);\n })\n .on(\"changed\", function (log) {\n });\n\n\nThe hash of the signature of the event is one of the topics, except if you\ndeclared the event with the ``anonymous`` specifier. This means that it is\nnot possible to filter for specific anonymous events by name, you can\nonly filter by the contract address. The advantage of anonymous events\nis that they are cheaper to deploy and call. It also allows you to declare\nfour indexed arguments rather than three.\n\n.. note::\n Since the transaction log only stores the event data and not the type,\n you have to know the type of the event, including which parameter is\n indexed and if the event is anonymous in order to correctly interpret\n the data.\n In particular, it is possible to \"fake\" the signature of another event\n using an anonymous event.\n\n.. index:: ! selector; of an event\n\nMembers of Events\n=================\n\n- ``event.selector``: For non-anonymous events, this is a ``bytes32`` value\n containing the ``keccak256`` hash of the event signature, as used in the default topic.\n\n\nExample\n=======\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.21 <0.9.0;\n\n contract ClientReceipt {\n event Deposit(\n address indexed from,\n bytes32 indexed id,\n uint value\n );\n\n function deposit(bytes32 id) public payable {\n // Events are emitted using `emit`, followed by\n // the name of the event and the arguments\n // (if any) in parentheses. Any such invocation\n // (even deeply nested) can be detected from\n // the JavaScript API by filtering for `Deposit`.\n emit Deposit(msg.sender, id, msg.value);\n }\n }\n\nThe use in the JavaScript API is as follows:\n\n.. code-block:: javascript\n\n var abi = /* abi as generated by the compiler */;\n var ClientReceipt = web3.eth.contract(abi);\n var clientReceipt = ClientReceipt.at(\"0x1234...ab67\" /* address */);\n\n var depositEvent = clientReceipt.Deposit();\n\n // watch for changes\n depositEvent.watch(function(error, result){\n // result contains non-indexed arguments and topics\n // given to the `Deposit` call.\n if (!error)\n console.log(result);\n });\n\n\n // Or pass a callback to start watching immediately\n var depositEvent = clientReceipt.Deposit(function(error, result) {\n if (!error)\n console.log(result);\n });\n\nThe output of the above looks like the following (trimmed):\n\n.. code-block:: json\n\n {\n \"returnValues\": {\n \"from\": \"0x1111…FFFFCCCC\",\n \"id\": \"0x50…sd5adb20\",\n \"value\": \"0x420042\"\n },\n \"raw\": {\n \"data\": \"0x7f…91385\",\n \"topics\": [\"0xfd4…b4ead7\", \"0x7f…1a91385\"]\n }\n }\n\nAdditional Resources for Understanding Events\n=============================================\n\n- `JavaScript documentation `_\n- `Example usage of events `_\n- `How to access them in js `_\n" }, { "path": "docs/contracts/function-modifiers.rst", "content": ".. index:: ! function;modifier\n\n.. _modifiers:\n\n******************\nFunction Modifiers\n******************\n\nModifiers can be used to change the behavior of functions in a declarative way.\nFor example,\nyou can use a modifier to automatically check a condition prior to executing the function.\n\nModifiers are\ninheritable properties of contracts and may be overridden by derived contracts, but only\nif they are marked ``virtual``. For details, please see\n:ref:`Modifier Overriding `.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.1 <0.9.0;\n\n contract owned {\n constructor() { owner = payable(msg.sender); }\n address payable owner;\n\n // This contract only defines a modifier but does not use\n // it: it will be used in derived contracts.\n // The function body is inserted where the special symbol\n // `_;` in the definition of a modifier appears.\n // This means that if the owner calls this function, the\n // function is executed and otherwise, an exception is\n // thrown.\n modifier onlyOwner {\n require(\n msg.sender == owner,\n \"Only owner can call this function.\"\n );\n _;\n }\n }\n\n contract priced {\n // Modifiers can receive arguments:\n modifier costs(uint price) {\n if (msg.value >= price) {\n _;\n }\n }\n }\n\n contract Register is priced, owned {\n mapping(address => bool) registeredAddresses;\n uint price;\n\n constructor(uint initialPrice) { price = initialPrice; }\n\n // It is important to also provide the\n // `payable` keyword here, otherwise the function will\n // automatically reject all Ether sent to it.\n function register() public payable costs(price) {\n registeredAddresses[msg.sender] = true;\n }\n\n // This contract inherits the `onlyOwner` modifier from\n // the `owned` contract. As a result, calls to `changePrice` will\n // only take effect if they are made by the stored owner.\n function changePrice(uint price_) public onlyOwner {\n price = price_;\n }\n }\n\n contract Mutex {\n bool locked;\n modifier noReentrancy() {\n require(\n !locked,\n \"Reentrant call.\"\n );\n locked = true;\n _;\n locked = false;\n }\n\n /// This function is protected by a mutex, which means that\n /// reentrant calls from within `msg.sender.call` cannot call `f` again.\n /// The `return 7` statement assigns 7 to the return value but still\n /// executes the statement `locked = false` in the modifier.\n function f() public noReentrancy returns (uint) {\n (bool success,) = msg.sender.call(\"\");\n require(success);\n return 7;\n }\n }\n\nIf you want to access a modifier ``m`` defined in a contract ``C``, you can use ``C.m`` to\nreference it without virtual lookup. It is only possible to use modifiers defined in the current\ncontract or its base contracts. Modifiers can also be defined in libraries but their use is\nlimited to functions of the same library.\n\nMultiple modifiers are applied to a function by specifying them in a\nwhitespace-separated list and are evaluated in the order presented.\n\nModifiers cannot implicitly access or change the arguments and return values of functions they modify.\nTheir values can only be passed to them explicitly at the point of invocation.\n\nIn function modifiers, it is necessary to specify when you want the function to which the modifier is\napplied to be run. The placeholder statement (denoted by a single underscore character ``_``) is used to\ndenote where the body of the function being modified should be inserted. Note that the\nplaceholder operator is different from using underscores as leading or trailing characters in variable\nnames, which is a stylistic choice.\n\nExplicit returns from a modifier or function body only leave the current\nmodifier or function body. Return variables are assigned and\ncontrol flow continues after the ``_`` in the preceding modifier.\n\n.. warning::\n In an earlier version of Solidity, ``return`` statements in functions\n having modifiers behaved differently.\n\nAn explicit return from a modifier with ``return;`` does not affect the values returned by the function.\nThe modifier can, however, choose not to execute the function body at all and in that case the return\nvariables are set to their :ref:`default values` just as if the function had an empty\nbody.\n\nThe ``_`` symbol can appear in the modifier multiple times. Each occurrence is replaced with\nthe function body, and the function returns the return value of the final occurrence.\n\nArbitrary expressions are allowed for modifier arguments and in this context,\nall symbols visible from the function are visible in the modifier. Symbols\nintroduced in the modifier are not visible in the function (as they might\nchange by overriding).\n" }, { "path": "docs/contracts/functions.rst", "content": ".. index:: ! functions, ! function;free\n\n.. _functions:\n\n*********\nFunctions\n*********\n\nFunctions can be defined inside and outside of contracts.\n\nFunctions outside of a contract, also called \"free functions\", always have implicit ``internal``\n:ref:`visibility`. Their code is included in all contracts\nthat call them, similar to internal library functions.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.1 <0.9.0;\n\n function sum(uint[] memory arr) pure returns (uint s) {\n for (uint i = 0; i < arr.length; i++)\n s += arr[i];\n }\n\n contract ArrayExample {\n bool found;\n function f(uint[] memory arr) public {\n // This calls the free function internally.\n // The compiler will add its code to the contract.\n uint s = sum(arr);\n require(s >= 10);\n found = true;\n }\n }\n\n.. note::\n Functions defined outside a contract are still always executed\n in the context of a contract.\n They still can call other contracts, send them Ether and destroy the contract that called them,\n among other things. The main difference to functions defined inside a contract\n is that free functions do not have direct access to the variable ``this``, storage variables and functions\n not in their scope.\n\n.. _function-parameters-return-variables:\n\nFunction Parameters and Return Variables\n========================================\n\nFunctions take typed parameters as input and may, unlike in many other\nlanguages, also return an arbitrary number of values as output.\n\nFunction Parameters\n-------------------\n\nFunction parameters are declared the same way as variables, and the name of\nunused parameters can be omitted.\n\nFor example, if you want your contract to accept one kind of external call\nwith two integers, you would use something like the following:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract Simple {\n uint sum;\n function taker(uint a, uint b) public {\n sum = a + b;\n }\n }\n\nFunction parameters can be used as any other local variable and they can also be assigned to.\n\n.. index:: return array, return string, array, string, array of strings, dynamic array, variably sized array, return struct, struct\n\nReturn Variables\n----------------\n\nFunction return variables are declared with the same syntax after the\n``returns`` keyword.\n\nFor example, suppose you want to return two results: the sum and the product of\ntwo integers passed as function parameters, then you use something like:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract Simple {\n function arithmetic(uint a, uint b)\n public\n pure\n returns (uint sum, uint product)\n {\n sum = a + b;\n product = a * b;\n }\n }\n\nThe names of return variables can be omitted.\nReturn variables can be used as any other local variable and they\nare initialized with their :ref:`default value ` and have that\nvalue until they are (re-)assigned.\n\nYou can either explicitly assign to return variables and\nthen leave the function as above,\nor you can provide return values\n(either a single or :ref:`multiple ones`) directly with the ``return``\nstatement:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract Simple {\n function arithmetic(uint a, uint b)\n public\n pure\n returns (uint sum, uint product)\n {\n return (a + b, a * b);\n }\n }\n\nIf you use an early ``return`` to leave a function that has return variables,\nyou must provide return values together with the return statement.\n\n.. note::\n You cannot return some types from non-internal functions.\n This includes the types listed below and any composite types that recursively contain them:\n\n - mappings,\n - internal function types,\n - reference types with location set to ``storage``,\n - multi-dimensional arrays (applies only to :ref:`ABI coder v1 `),\n - structs (applies only to :ref:`ABI coder v1 `).\n\n This restriction does not apply to library functions because of their different :ref:`internal ABI `.\n\n.. _multi-return:\n\nReturning Multiple Values\n-------------------------\n\nWhen a function has multiple return types, the statement ``return (v0, v1, ..., vn)`` can be used to return multiple values.\nThe number of components must be the same as the number of return variables\nand their types have to match, potentially after an :ref:`implicit conversion `.\n\n.. _state-mutability:\n\nState Mutability\n================\n\n.. index:: ! view function, function;view\n\n.. _view-functions:\n\nView Functions\n--------------\n\nFunctions can be declared ``view`` in which case they promise not to modify the state.\n\n.. note::\n If the compiler's EVM target is Byzantium or newer (default) the opcode\n ``STATICCALL`` is used when ``view`` functions are called, which enforces the state\n to stay unmodified as part of the EVM execution. For library ``view`` functions\n ``DELEGATECALL`` is used, because there is no combined ``DELEGATECALL`` and ``STATICCALL``.\n This means library ``view`` functions do not have run-time checks that prevent state\n modifications. This should not impact security negatively because library code is\n usually known at compile-time and the static checker performs compile-time checks.\n\nThe following statements are considered modifying the state:\n\n#. Writing to state variables (storage and transient storage).\n#. :ref:`Emitting events `.\n#. :ref:`Creating other contracts `.\n#. Using ``selfdestruct``.\n#. Sending Ether via calls.\n#. Calling any function not marked ``view`` or ``pure``.\n#. Using low-level calls.\n#. Using inline assembly that contains certain opcodes.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n\n contract C {\n function f(uint a, uint b) public view returns (uint) {\n return a * (b + 42) + block.timestamp;\n }\n }\n\n.. note::\n ``constant`` on functions used to be an alias to ``view``, but this was dropped in version 0.5.0.\n\n.. note::\n Getter methods are automatically marked ``view``.\n\n.. note::\n Prior to version 0.5.0, the compiler did not use the ``STATICCALL`` opcode\n for ``view`` functions.\n This enabled state modifications in ``view`` functions through the use of\n invalid explicit type conversions.\n By using ``STATICCALL`` for ``view`` functions, modifications to the\n state are prevented on the level of the EVM.\n\n.. index:: ! pure function, function;pure\n\n.. _pure-functions:\n\nPure Functions\n--------------\n\nFunctions can be declared ``pure`` in which case they promise not to read from or modify the state.\nIn particular, it should be possible to evaluate a ``pure`` function at compile-time given\nonly its inputs and ``msg.data``, but without any knowledge of the current blockchain state.\nThis means that reading from ``immutable`` variables can be a non-pure operation.\n\n.. note::\n If the compiler's EVM target is Byzantium or newer (default) the opcode ``STATICCALL`` is used,\n which does not guarantee that the state is not read, but at least that it is not modified.\n\nIn addition to the list of state modifying statements explained above, the following are considered reading from the state:\n\n#. Reading from state variables (storage and transient storage).\n#. Accessing ``address(this).balance`` or ``
.balance``.\n#. Accessing any of the members of ``block``, ``tx``, ``msg`` (with the exception of ``msg.sig`` and ``msg.data``).\n#. Calling any function not marked ``pure``.\n#. Using inline assembly that contains certain opcodes.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n\n contract C {\n function f(uint a, uint b) public pure returns (uint) {\n return a * (b + 42);\n }\n }\n\nPure functions are able to use the ``revert()`` and ``require()`` functions to revert\npotential state changes when an :ref:`error occurs `.\n\nReverting a state change is not considered a \"state modification\", as only changes to the\nstate made previously in code that did not have the ``view`` or ``pure`` restriction\nare reverted and that code has the option to catch the ``revert`` and not pass it on.\n\nThis behavior is also in line with the ``STATICCALL`` opcode.\n\n.. warning::\n It is not possible to prevent functions from reading the state at the level\n of the EVM, it is only possible to prevent them from writing to the state\n (i.e. only ``view`` can be enforced at the EVM level, ``pure`` can not).\n\n.. note::\n Prior to version 0.5.0, the compiler did not use the ``STATICCALL`` opcode\n for ``pure`` functions.\n This enabled state modifications in ``pure`` functions through the use of\n invalid explicit type conversions.\n By using ``STATICCALL`` for ``pure`` functions, modifications to the\n state are prevented on the level of the EVM.\n\n.. note::\n Prior to version 0.4.17 the compiler did not enforce that ``pure`` is not reading the state.\n It is a compile-time type check, which can be circumvented by doing invalid explicit conversions\n between contract types, because the compiler can verify that the type of the contract does\n not do state-changing operations, but it cannot check that the contract that will be called\n at runtime is actually of that type.\n\n.. _special-functions:\n\nSpecial Functions\n=================\n\n.. index:: ! receive ether function, function;receive, ! receive\n\n.. _receive-ether-function:\n\nReceive Ether Function\n----------------------\n\nA contract can have at most one ``receive`` function, declared using\n``receive() external payable { ... }``\n(without the ``function`` keyword).\nThis function cannot have arguments, cannot return anything and must have\n``external`` visibility and ``payable`` state mutability.\nIt can be virtual, can override and can have modifiers.\n\nThe receive function is executed on a\ncall to the contract with empty calldata. This is the function that is executed\non plain Ether transfers (e.g. via ``.send()`` or ``.transfer()``). If no such\nfunction exists, but a payable :ref:`fallback function `\nexists, the fallback function will be called on a plain Ether transfer. If\nneither a receive Ether nor a payable fallback function is present, the\ncontract cannot receive Ether through a transaction that does not represent a payable function call and throws an\nexception.\n\nIn the worst case, the ``receive`` function can only rely on 2300 gas being\navailable (for example when ``send`` or ``transfer`` is used), leaving little\nroom to perform other operations except basic logging. The following operations\nwill consume more gas than the 2300 gas stipend:\n\n- Writing to storage\n- Creating a contract\n- Calling an external function which consumes a large amount of gas\n- Sending Ether\n\n.. warning::\n ``send()`` and ``transfer()`` are deprecated and scheduled for removal.\n See the section on :ref:`send ` and :ref:`transfer ` for more information.\n\n.. warning::\n When Ether is sent directly to a contract (without a function call, i.e. sender uses ``send`` or ``transfer``)\n but the receiving contract does not define a receive Ether function or a payable fallback function,\n an exception will be thrown, sending back the Ether (this was different\n before Solidity v0.4.0). If you want your contract to receive Ether,\n you have to implement a receive Ether function (using payable fallback functions for receiving Ether is\n not recommended, since the fallback is invoked and would not fail for interface confusions\n on the part of the sender).\n\n.. warning::\n A contract without a receive Ether function can receive Ether as a\n recipient of a *coinbase transaction* (aka *miner block reward*)\n or as a destination of a ``selfdestruct``.\n\n A contract cannot react to such Ether transfers and thus also\n cannot reject them. This is a design choice of the EVM and\n Solidity cannot work around it.\n\n It also means that ``address(this).balance`` can be higher\n than the sum of some manual accounting implemented in a\n contract (i.e. having a counter updated in the receive Ether function).\n\nBelow you can see an example of a Sink contract that uses function ``receive``.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n // This contract keeps all Ether sent to it with no way\n // to get it back.\n contract Sink {\n event Received(address, uint);\n receive() external payable {\n emit Received(msg.sender, msg.value);\n }\n }\n\n.. index:: ! fallback function, function;fallback\n\n.. _fallback-function:\n\nFallback Function\n-----------------\n\nA contract can have at most one ``fallback`` function, declared using either ``fallback () external [payable]``\nor ``fallback (bytes calldata input) external [payable] returns (bytes memory output)``\n(both without the ``function`` keyword).\nThis function must have ``external`` visibility. A fallback function can be virtual, can override\nand can have modifiers.\n\nThe fallback function is executed on a call to the contract if none of the other\nfunctions match the given function signature, or if no data was supplied at\nall and there is no :ref:`receive Ether function `.\nThe fallback function always receives data, but in order to also receive Ether\nit must be marked ``payable``.\n\nIf the version with parameters is used, ``input`` will contain the full data sent to the contract\n(equal to ``msg.data``) and can return data in ``output``. The returned data will not be\nABI-encoded. Instead it will be returned without modifications (not even padding).\n\nIn the worst case, if a payable fallback function is also used in\nplace of a receive function, it can only rely on 2300 gas being\navailable (see :ref:`receive Ether function `\nfor a brief description of the implications of this).\n\nLike any function, the fallback function can execute complex\noperations as long as there is enough gas passed on to it.\n\n.. warning::\n A ``payable`` fallback function is also executed for\n plain Ether transfers, if no :ref:`receive Ether function `\n is present. It is recommended to always define a receive Ether\n function as well, if you define a payable fallback function\n to distinguish Ether transfers from interface confusions.\n\n.. note::\n If you want to decode the input data, you can check the first four bytes\n for the function selector and then\n you can use ``abi.decode`` together with the array slice syntax to\n decode ABI-encoded data:\n ``(c, d) = abi.decode(input[4:], (uint256, uint256));``\n Note that this should only be used as a last resort and\n proper functions should be used instead.\n\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.2 <0.9.0;\n\n contract Test {\n uint x;\n // This function is called for all messages sent to\n // this contract (there is no other function).\n // Sending Ether to this contract will cause an exception,\n // because the fallback function does not have the `payable`\n // modifier.\n fallback() external { x = 1; }\n }\n\n contract TestPayable {\n uint x;\n uint y;\n // This function is called for all messages sent to\n // this contract, except plain Ether transfers\n // (there is no other function except the receive function).\n // Any call with non-empty calldata to this contract will execute\n // the fallback function (even if Ether is sent along with the call).\n fallback() external payable { x = 1; y = msg.value; }\n\n // This function is called for plain Ether transfers, i.e.\n // for every call with empty calldata.\n receive() external payable { x = 2; y = msg.value; }\n }\n\n contract Caller {\n function callTest(Test test) public returns (bool) {\n (bool success,) = address(test).call(abi.encodeWithSignature(\"nonExistingFunction()\"));\n require(success);\n // results in test.x becoming == 1.\n\n // address(test) will not allow to call ``send`` directly, since ``test`` has no payable\n // fallback function.\n // It has to be converted to the ``address payable`` type to even allow calling ``send`` on it.\n address payable testPayable = payable(address(test));\n\n // If someone sends Ether to that contract,\n // the transfer will fail, i.e. this returns false here.\n // This will report a warning (deprecation)\n return testPayable.send(2 ether);\n }\n\n function callTestPayable(TestPayable test) public returns (bool) {\n (bool success,) = address(test).call(abi.encodeWithSignature(\"nonExistingFunction()\"));\n require(success);\n // results in test.x becoming == 1 and test.y becoming 0.\n (success,) = address(test).call{value: 1}(abi.encodeWithSignature(\"nonExistingFunction()\"));\n require(success);\n // results in test.x becoming == 1 and test.y becoming 1.\n\n // If someone sends Ether to that contract, the receive function in TestPayable will be called.\n // Since that function writes to storage, it takes more gas than is available with a\n // simple ``send`` or ``transfer``. Because of that, we have to use a low-level call.\n (success,) = address(test).call{value: 2 ether}(\"\");\n require(success);\n // results in test.x becoming == 2 and test.y becoming 2 ether.\n\n return true;\n }\n }\n\n.. index:: ! overload\n\n.. _overload-function:\n\nFunction Overloading\n====================\n\nA contract can have multiple functions of the same name but with different parameter\ntypes.\nThis process is called \"overloading\" and also applies to inherited functions.\nThe following example shows overloading of the function\n``f`` in the scope of contract ``A``.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract A {\n function f(uint value) public pure returns (uint out) {\n out = value;\n }\n\n function f(uint value, bool really) public pure returns (uint out) {\n if (really)\n out = value;\n }\n }\n\nOverloaded functions are also present in the external interface. It is an error if two\nexternally visible functions differ by their Solidity types but not by their external types.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n // This will not compile\n contract A {\n function f(B value) public pure returns (B out) {\n out = value;\n }\n\n function f(address value) public pure returns (address out) {\n out = value;\n }\n }\n\n contract B {\n }\n\n\nBoth ``f`` function overloads above end up accepting the address type for the ABI although\nthey are considered different inside Solidity.\n\nOverload resolution and Argument matching\n-----------------------------------------\n\nOverloaded functions are selected by matching the function declarations in the current scope\nto the arguments supplied in the function call. Functions are selected as overload candidates\nif all arguments can be implicitly converted to the expected types. If there is not exactly one\ncandidate, resolution fails.\n\n.. note::\n Return parameters are not taken into account for overload resolution.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract A {\n function f(uint8 val) public pure returns (uint8 out) {\n out = val;\n }\n\n function f(uint256 val) public pure returns (uint256 out) {\n out = val;\n }\n }\n\nCalling ``f(50)`` would create a type error since ``50`` can be implicitly converted both to ``uint8``\nand ``uint256`` types. On another hand ``f(256)`` would resolve to ``f(uint256)`` overload as ``256`` cannot be implicitly\nconverted to ``uint8``.\n" }, { "path": "docs/contracts/inheritance.rst", "content": ".. index:: ! inheritance, ! base class, ! contract;base, ! deriving\n\n***********\nInheritance\n***********\n\nSolidity supports multiple inheritance including polymorphism.\n\nPolymorphism means that a function call (internal and external)\nalways executes the function of the same name (and parameter types)\nin the most derived contract in the inheritance hierarchy.\nThis has to be explicitly enabled on each function in the\nhierarchy using the ``virtual`` and ``override`` keywords.\nSee :ref:`Function Overriding ` for more details.\n\nIt is possible to call functions further up in the inheritance\nhierarchy internally by explicitly specifying the contract\nusing ``ContractName.functionName()`` or using ``super.functionName()``\nif you want to call the function one level higher up in\nthe flattened inheritance hierarchy (see below).\n\nWhen a contract inherits from other contracts, only a single\ncontract is created on the blockchain, and the code from all the base contracts\nis compiled into the created contract. This means that all internal calls\nto functions of base contracts also just use internal function calls\n(``super.f(..)`` will use JUMP and not a message call).\n\nState variable shadowing is considered as an error. A derived contract can\nonly declare a state variable ``x``, if there is no visible state variable\nwith the same name in any of its bases.\n\nThe general inheritance system is very similar to\n`Python's `_,\nespecially concerning multiple inheritance, but there are also\nsome :ref:`differences `.\n\nDetails are given in the following example.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n contract Owned {\n address payable owner;\n constructor() { owner = payable(msg.sender); }\n }\n\n // Use `is` to derive from another contract. Derived\n // contracts can access all non-private members including\n // internal functions and state variables. These cannot be\n // accessed externally via `this`, though.\n contract Emittable is Owned {\n event Emitted();\n\n // The keyword `virtual` means that the function can change\n // its behavior in derived classes (\"overriding\").\n function emitEvent() virtual public {\n if (msg.sender == owner)\n emit Emitted();\n }\n }\n\n // These abstract contracts are only provided to make the\n // interface known to the compiler. Note the function\n // without body. If a contract does not implement all\n // functions it can only be used as an interface.\n abstract contract Config {\n function lookup(uint id) public virtual returns (address adr);\n }\n\n abstract contract NameReg {\n function register(bytes32 name) public virtual;\n function unregister() public virtual;\n }\n\n // Multiple inheritance is possible. Note that `Owned` is\n // also a base class of `Emittable`, yet there is only a single\n // instance of `Owned` (as for virtual inheritance in C++).\n contract Named is Owned, Emittable {\n constructor(bytes32 name) {\n Config config = Config(0xD5f9D8D94886E70b06E474c3fB14Fd43E2f23970);\n NameReg(config.lookup(1)).register(name);\n }\n\n // Functions can be overridden by another function with the same name and\n // the same number/types of inputs. If the overriding function has different\n // types of output parameters, that causes an error.\n // Both local and message-based function calls take these overrides\n // into account.\n // If you want the function to override, you need to use the\n // `override` keyword. You need to specify the `virtual` keyword again\n // if you want this function to be overridden again.\n function emitEvent() public virtual override {\n if (msg.sender == owner) {\n Config config = Config(0xD5f9D8D94886E70b06E474c3fB14Fd43E2f23970);\n NameReg(config.lookup(1)).unregister();\n // It is still possible to call a specific\n // overridden function.\n Emittable.emitEvent();\n }\n }\n }\n\n\n // If a constructor takes an argument, it needs to be\n // provided in the header or modifier-invocation-style at\n // the constructor of the derived contract (see below).\n contract PriceFeed is Owned, Emittable, Named(\"GoldFeed\") {\n uint info;\n\n function updateInfo(uint newInfo) public {\n if (msg.sender == owner) info = newInfo;\n }\n\n // Here, we only specify `override` and not `virtual`.\n // This means that contracts deriving from `PriceFeed`\n // cannot change the behavior of `emitEvent` anymore.\n function emitEvent() public override(Emittable, Named) { Named.emitEvent(); }\n function get() public view returns(uint r) { return info; }\n }\n\nNote that above, we call ``Emittable.emitEvent()`` to \"forward\" the\nemit event request. The way this is done is problematic, as\nseen in the following example:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n contract Owned {\n address payable owner;\n constructor() { owner = payable(msg.sender); }\n }\n\n contract Emittable is Owned {\n event Emitted();\n\n function emitEvent() virtual public {\n if (msg.sender == owner) {\n emit Emitted();\n }\n }\n }\n\n contract Base1 is Emittable {\n event Base1Emitted();\n function emitEvent() public virtual override {\n /* Here, we emit an event to simulate some Base1 logic */\n emit Base1Emitted();\n Emittable.emitEvent();\n }\n }\n\n contract Base2 is Emittable {\n event Base2Emitted();\n function emitEvent() public virtual override {\n /* Here, we emit an event to simulate some Base2 logic */\n emit Base2Emitted();\n Emittable.emitEvent();\n }\n }\n\n contract Final is Base1, Base2 {\n event FinalEmitted();\n function emitEvent() public override(Base1, Base2) {\n /* Here, we emit an event to simulate some Final logic */\n emit FinalEmitted();\n Base2.emitEvent();\n }\n }\n\nA call to ``Final.emitEvent()`` will call ``Base2.emitEvent`` because we specify it\nexplicitly in the final override, but this function will bypass\n``Base1.emitEvent``, resulting in the following sequence of events:\n``FinalEmitted -> Base2Emitted -> Emitted``, instead of the expected sequence:\n``FinalEmitted -> Base2Emitted -> Base1Emitted -> Emitted``.\nThe way around this is to use ``super``:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n contract Owned {\n address payable owner;\n constructor() { owner = payable(msg.sender); }\n }\n\n contract Emittable is Owned {\n event Emitted();\n\n function emitEvent() virtual public {\n if (msg.sender == owner) {\n emit Emitted();\n }\n }\n }\n\n contract Base1 is Emittable {\n event Base1Emitted();\n function emitEvent() public virtual override {\n /* Here, we emit an event to simulate some Base1 logic */\n emit Base1Emitted();\n super.emitEvent();\n }\n }\n\n\n contract Base2 is Emittable {\n event Base2Emitted();\n function emitEvent() public virtual override {\n /* Here, we emit an event to simulate some Base2 logic */\n emit Base2Emitted();\n super.emitEvent();\n }\n }\n\n contract Final is Base1, Base2 {\n event FinalEmitted();\n function emitEvent() public override(Base1, Base2) {\n /* Here, we emit an event to simulate some Final logic */\n emit FinalEmitted();\n super.emitEvent();\n }\n }\n\nIf ``Final`` calls a function of ``super``, it does not simply\ncall this function on one of its base contracts. Rather, it\ncalls this function on the next base contract in the final\ninheritance graph, so it will call ``Base1.emitEvent()`` (note that\nthe final inheritance sequence is -- starting with the most\nderived contract: Final, Base2, Base1, Emittable, Owned).\nThe actual function that is called when using super is\nnot known in the context of the class where it is used,\nalthough its type is known. This is similar for ordinary\nvirtual method lookup.\n\n.. index:: ! overriding;function\n\n.. _function-overriding:\n\nFunction Overriding\n===================\n\nBase functions can be overridden by inheriting contracts to change their\nbehavior if they are marked as ``virtual``. The overriding function must then\nuse the ``override`` keyword in the function header.\nThe overriding function may only change the visibility of the overridden function from ``external`` to ``public``.\nThe mutability may be changed to a more strict one following the order:\n``nonpayable`` can be overridden by ``view`` and ``pure``. ``view`` can be overridden by ``pure``.\n``payable`` is an exception and cannot be changed to any other mutability.\n\nThe following example demonstrates changing mutability and visibility:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n contract Base\n {\n function foo() virtual external view {}\n }\n\n contract Middle is Base {}\n\n contract Inherited is Middle\n {\n function foo() override public pure {}\n }\n\nFor multiple inheritance, the most derived base contracts that define the same\nfunction must be specified explicitly after the ``override`` keyword.\nIn other words, you have to specify all base contracts that define the same function\nand have not yet been overridden by another base contract (on some path through the inheritance graph).\nAdditionally, if a contract inherits the same function from multiple (unrelated)\nbases, it has to explicitly override it:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n contract Base1\n {\n function foo() virtual public {}\n }\n\n contract Base2\n {\n function foo() virtual public {}\n }\n\n contract Inherited is Base1, Base2\n {\n // Derives from multiple bases defining foo(), so we must explicitly\n // override it\n function foo() public override(Base1, Base2) {}\n }\n\nAn explicit override specifier is not required if\nthe function is defined in a common base contract\nor if there is a unique function in a common base contract\nthat already overrides all other functions.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n contract A { function f() public pure{} }\n contract B is A {}\n contract C is A {}\n // No explicit override required\n contract D is B, C {}\n\nMore formally, it is not required to override a function (directly or\nindirectly) inherited from multiple bases if there is a base contract\nthat is part of all override paths for the signature, and (1) that\nbase implements the function and no paths from the current contract\nto the base mentions a function with that signature or (2) that base\ndoes not implement the function and there is at most one mention of\nthe function in all paths from the current contract to that base.\n\nIn this sense, an override path for a signature is a path through\nthe inheritance graph that starts at the contract under consideration\nand ends at a contract mentioning a function with that signature\nthat does not override.\n\nIf you do not mark a function that overrides as ``virtual``, derived\ncontracts can no longer change the behavior of that function.\n\n.. note::\n\n Functions with the ``private`` visibility cannot be ``virtual``.\n\n.. note::\n\n Functions without implementation have to be marked ``virtual``\n outside of interfaces. In interfaces, all functions are\n automatically considered ``virtual``.\n\n.. note::\n\n Starting from Solidity 0.8.8, the ``override`` keyword is not\n required when overriding an interface function, except for the\n case where the function is defined in multiple bases.\n\n\nPublic state variables can override external functions if the\nparameter and return types of the function matches the getter function\nof the variable:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n contract A\n {\n function f() external view virtual returns(uint) { return 5; }\n }\n\n contract B is A\n {\n uint public override f;\n }\n\n.. note::\n\n While public state variables can override external functions, they themselves cannot\n be overridden.\n\n.. index:: ! overriding;modifier\n\n.. _modifier-overriding:\n\nModifier Overriding (deprecated)\n================================\n\nFunction modifiers can override each other. This works in the same way as\n:ref:`function overriding ` (except that there is no overloading for modifiers). The\n``virtual`` keyword must be used on the overridden modifier\nand the ``override`` keyword must be used in the overriding modifier:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n contract Base\n {\n // This will report a warning (deprecation)\n modifier foo() virtual {_;}\n }\n\n contract Inherited is Base\n {\n modifier foo() override {_;}\n }\n\n\nIn case of multiple inheritance, all direct base contracts must be specified\nexplicitly:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n contract Base1\n {\n // This will report a warning (deprecation)\n modifier foo() virtual {_;}\n }\n\n contract Base2\n {\n // This will report a warning (deprecation)\n modifier foo() virtual {_;}\n }\n\n contract Inherited is Base1, Base2\n {\n modifier foo() override(Base1, Base2) {_;}\n }\n\n.. warning::\n ``virtual`` modifiers are deprecated and scheduled for removal.\n\n\n.. index:: ! constructor\n\n.. _constructor:\n\nConstructors\n============\n\nA constructor is an optional function declared with the ``constructor`` keyword\nwhich is executed upon contract creation, and where you can run contract\ninitialization code.\n\nBefore the constructor code is executed, state variables are initialised to\ntheir specified value if you initialise them inline, or their :ref:`default value` if you do not.\n\nAfter the constructor has run, the final code of the contract is deployed\nto the blockchain. The deployment of\nthe code costs additional gas linear to the length of the code.\nThis code includes all functions that are part of the public interface\nand all functions that are reachable from there through function calls.\nIt does not include the constructor code or internal functions that are\nonly called from the constructor.\n\nIf there is no\nconstructor, the contract will assume the default constructor, which is\nequivalent to ``constructor() {}``. For example:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n abstract contract A {\n uint public a;\n\n constructor(uint a_) {\n a = a_;\n }\n }\n\n contract B is A(1) {\n constructor() {}\n }\n\nYou can use internal parameters in a constructor (for example storage pointers). In this case,\nthe contract has to be marked :ref:`abstract `, because these parameters\ncannot be assigned valid values from outside but only through the constructors of derived contracts.\n\n.. warning::\n Prior to version 0.4.22, constructors were defined as functions with the same name as the contract.\n This syntax was deprecated and is not allowed anymore in version 0.5.0.\n\n.. warning::\n Prior to version 0.7.0, you had to specify the visibility of constructors as either\n ``internal`` or ``public``.\n\n\n.. index:: ! base;constructor, inheritance list, contract;abstract, abstract contract\n\nArguments for Base Constructors\n===============================\n\nThe constructors of all the base contracts will be called following the\nlinearization rules explained below. If the base constructors have arguments,\nderived contracts need to specify all of them. This can be done in two ways:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n contract Base {\n uint x;\n constructor(uint x_) { x = x_; }\n }\n\n // Either directly specify in the inheritance list...\n contract Derived1 is Base(7) {\n constructor() {}\n }\n\n // or through a \"modifier\" of the derived constructor...\n contract Derived2 is Base {\n constructor(uint y) Base(y * y) {}\n }\n\n // or declare abstract...\n abstract contract Derived3 is Base {\n }\n\n // and have the next concrete derived contract initialize it.\n contract DerivedFromDerived is Derived3 {\n constructor() Base(10 + 10) {}\n }\n\nOne way is directly in the inheritance list (``is Base(7)``). The other is in\nthe way a modifier is invoked as part of\nthe derived constructor (``Base(y * y)``). The first way to\ndo it is more convenient if the constructor argument is a\nconstant and defines the behavior of the contract or\ndescribes it. The second way has to be used if the\nconstructor arguments of the base depend on those of the\nderived contract. Arguments have to be given either in the\ninheritance list or in modifier-style in the derived constructor.\nSpecifying arguments in both places is an error.\n\nIf a derived contract does not specify the arguments to all of its base\ncontracts' constructors, it must be declared abstract. In that case, when\nanother contract derives from it, that other contract's inheritance list\nor constructor must provide the necessary parameters\nfor all base classes that haven't had their parameters specified (otherwise,\nthat other contract must be declared abstract as well). For example, in the above\ncode snippet, see ``Derived3`` and ``DerivedFromDerived``.\n\n.. index:: ! inheritance;multiple, ! linearization, ! C3 linearization\n\n.. _multi-inheritance:\n\nMultiple Inheritance and Linearization\n======================================\n\nLanguages that allow multiple inheritance have to deal with\nseveral problems. One is the `Diamond Problem `_.\nSolidity is similar to Python in that it uses C3 Linearization\nto force a specific order in the directed acyclic graph (DAG) of base classes. This\nresults in the desirable property of monotonicity but\ndisallows some inheritance graphs. Especially, the order in\nwhich the base classes are given in the ``is`` directive is\nimportant: You have to list the direct base contracts\nin the order from \"most base-like\" to \"most derived\".\nNote that this order is the reverse of the one used in Python.\n\nAnother simplifying way to explain this is that when a function is called that\nis defined multiple times in different contracts, the given bases\nare searched from right to left (left to right in Python) in a depth-first manner,\nstopping at the first match. If a base contract has already been searched, it is skipped.\n\nIn the following code, Solidity will give the\nerror \"Linearization of inheritance graph impossible\".\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.0 <0.9.0;\n\n contract X {}\n contract A is X {}\n // This will not compile\n contract C is A, X {}\n\nThe reason for this is that ``C`` requests ``X`` to override ``A``\n(by specifying ``A, X`` in this order), but ``A`` itself\nrequests to override ``X``, which is a contradiction that\ncannot be resolved.\n\nDue to the fact that you have to explicitly override a function\nthat is inherited from multiple bases without a unique override,\nC3 linearization is not too important in practice.\n\nOne area where inheritance linearization is especially important and perhaps not as clear is when there are multiple constructors in the inheritance hierarchy. The constructors will always be executed in the linearized order, regardless of the order in which their arguments are provided in the inheriting contract's constructor. For example:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n contract Base1 {\n constructor() {}\n }\n\n contract Base2 {\n constructor() {}\n }\n\n // Constructors are executed in the following order:\n // 1 - Base1\n // 2 - Base2\n // 3 - Derived1\n contract Derived1 is Base1, Base2 {\n constructor() Base1() Base2() {}\n }\n\n // Constructors are executed in the following order:\n // 1 - Base2\n // 2 - Base1\n // 3 - Derived2\n contract Derived2 is Base2, Base1 {\n constructor() Base2() Base1() {}\n }\n\n // Constructors are still executed in the following order:\n // 1 - Base2\n // 2 - Base1\n // 3 - Derived3\n contract Derived3 is Base2, Base1 {\n constructor() Base1() Base2() {}\n }\n\n\nInheriting Different Kinds of Members of the Same Name\n======================================================\n\nThe only situations where, due to inheritance, a contract may contain multiple definitions sharing\nthe same name are:\n\n- Overloading of functions.\n- Overriding of virtual functions.\n- Overriding of external virtual functions by state variable getters.\n- Overriding of virtual modifiers.\n- Overloading of events.\n" }, { "path": "docs/contracts/interfaces.rst", "content": ".. index:: ! contract;interface, ! interface contract\n\n.. _interfaces:\n\n**********\nInterfaces\n**********\n\nInterfaces are similar to abstract contracts, but they cannot have any functions implemented.\nThere are further restrictions:\n\n- They cannot inherit from other contracts, but they can inherit from other interfaces.\n- All declared functions must be external in the interface, even if they are public in the contract.\n- They cannot declare a constructor.\n- They cannot declare state variables.\n- They cannot declare modifiers.\n\nSome of these restrictions might be lifted in the future.\n\nInterfaces are basically limited to what the Contract ABI can represent, and the conversion between the ABI and\nan interface should be possible without any information loss.\n\nInterfaces are denoted by their own keyword:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.2 <0.9.0;\n\n interface Token {\n enum TokenType { Fungible, NonFungible }\n struct Coin { string obverse; string reverse; }\n function transfer(address recipient, uint amount) external;\n }\n\nContracts can inherit interfaces as they would inherit other contracts.\n\nAll functions declared in interfaces are implicitly ``virtual`` and any\nfunctions that override them do not need the ``override`` keyword.\nThis does not automatically mean that an overriding function can be overridden again -\nthis is only possible if the overriding function is marked ``virtual``.\n\nInterfaces can inherit from other interfaces. This has the same rules as normal\ninheritance.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.2 <0.9.0;\n\n interface ParentA {\n function test() external returns (uint256);\n }\n\n interface ParentB {\n function test() external returns (uint256);\n }\n\n interface SubInterface is ParentA, ParentB {\n // Must redefine test in order to assert that the parent\n // meanings are compatible.\n function test() external override(ParentA, ParentB) returns (uint256);\n }\n\nTypes defined inside interfaces and other contract-like structures\ncan be accessed from other contracts: ``Token.TokenType`` or ``Token.Coin``.\n\n.. warning::\n\n Interfaces have supported ``enum`` types since :doc:`Solidity version 0.5.0 <050-breaking-changes>`, make\n sure the pragma version specifies this version as a minimum.\n" }, { "path": "docs/contracts/libraries.rst", "content": ".. index:: ! library, callcode, delegatecall\n\n.. _libraries:\n\n*********\nLibraries\n*********\n\nLibraries are similar to contracts, but their purpose is that they are deployed\nonly once at a specific address and their code is reused using the ``DELEGATECALL``\n(``CALLCODE`` until Homestead)\nfeature of the EVM. This means that if library functions are called, their code\nis executed in the context of the calling contract, i.e. ``this`` points to the\ncalling contract, and especially the storage from the calling contract can be\naccessed. As a library is an isolated piece of source code, it can only access\nstate variables of the calling contract if they are explicitly supplied (it\nwould have no way to name them, otherwise). Library functions can only be\ncalled directly (i.e. without the use of ``DELEGATECALL``) if they do not modify\nthe state (i.e. if they are ``view`` or ``pure`` functions),\nbecause libraries are assumed to be stateless. In particular, it is\nnot possible to destroy a library.\n\n.. note::\n Until version 0.4.20, it was possible to destroy libraries by\n circumventing Solidity's type system. Starting from that version,\n libraries contain a :ref:`mechanism` that\n disallows state-modifying functions\n to be called directly (i.e. without ``DELEGATECALL``).\n\nLibraries can be seen as implicit base contracts of the contracts that use them.\nThey will not be explicitly visible in the inheritance hierarchy, but calls\nto library functions look just like calls to functions of explicit base\ncontracts (using qualified access like ``L.f()``).\nOf course, calls to internal functions\nuse the internal calling convention, which means that all internal types\ncan be passed and types :ref:`stored in memory ` will be passed by reference and not copied.\nTo realize this in the EVM, the code of internal library functions\nthat are called from a contract\nand all functions called from therein will at compile time be included in the calling\ncontract, and a regular ``JUMP`` call will be used instead of a ``DELEGATECALL``.\n\n.. note::\n The inheritance analogy breaks down when it comes to public functions.\n Calling a public library function with ``L.f()`` results in an external call (``DELEGATECALL``\n to be precise).\n In contrast, ``A.f()`` is an internal call when ``A`` is a base contract of the current contract.\n\n.. index:: using for, set\n\nThe following example illustrates how to use libraries (but using a manual method,\nbe sure to check out :ref:`using for ` for a\nmore advanced example to implement a set).\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n\n // We define a new struct datatype that will be used to\n // hold its data in the calling contract.\n struct Data {\n mapping(uint => bool) flags;\n }\n\n library Set {\n // Note that the first parameter is of type \"storage\n // reference\" and thus only its storage address and not\n // its contents is passed as part of the call. This is a\n // special feature of library functions. It is idiomatic\n // to call the first parameter `self`, if the function can\n // be seen as a method of that object.\n function insert(Data storage self, uint value)\n public\n returns (bool)\n {\n if (self.flags[value])\n return false; // already there\n self.flags[value] = true;\n return true;\n }\n\n function remove(Data storage self, uint value)\n public\n returns (bool)\n {\n if (!self.flags[value])\n return false; // not there\n self.flags[value] = false;\n return true;\n }\n\n function contains(Data storage self, uint value)\n public\n view\n returns (bool)\n {\n return self.flags[value];\n }\n }\n\n\n contract C {\n Data knownValues;\n\n function register(uint value) public {\n // The library functions can be called without a\n // specific instance of the library, since the\n // \"instance\" will be the current contract.\n require(Set.insert(knownValues, value));\n }\n // In this contract, we can also directly access knownValues.flags, if we want.\n }\n\nOf course, you do not have to follow this way to use\nlibraries: they can also be used without defining struct\ndata types. Functions also work without any storage\nreference parameters, and they can have multiple storage reference\nparameters and in any position.\n\nThe calls to ``Set.contains``, ``Set.insert`` and ``Set.remove``\nare all compiled as calls (``DELEGATECALL``) to an external\ncontract/library. If you use libraries, be aware that an\nactual external function call is performed.\n``msg.sender``, ``msg.value`` and ``this`` will retain their values\nin this call, though (prior to Homestead, because of the use of ``CALLCODE``, ``msg.sender`` and\n``msg.value`` changed, though).\n\nThe following example shows how to use :ref:`types stored in memory ` and\ninternal functions in libraries in order to implement\ncustom types without the overhead of external function calls:\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.0;\n\n struct bigint {\n uint[] limbs;\n }\n\n library BigInt {\n function fromUint(uint x) internal pure returns (bigint memory r) {\n r.limbs = new uint[](1);\n r.limbs[0] = x;\n }\n\n function add(bigint memory a, bigint memory b) internal pure returns (bigint memory r) {\n r.limbs = new uint[](max(a.limbs.length, b.limbs.length));\n uint carry = 0;\n for (uint i = 0; i < r.limbs.length; ++i) {\n uint limbA = limb(a, i);\n uint limbB = limb(b, i);\n unchecked {\n r.limbs[i] = limbA + limbB + carry;\n\n if (limbA + limbB < limbA || (limbA + limbB == type(uint).max && carry > 0))\n carry = 1;\n else\n carry = 0;\n }\n }\n if (carry > 0) {\n // too bad, we have to add a limb\n uint[] memory newLimbs = new uint[](r.limbs.length + 1);\n uint i;\n for (i = 0; i < r.limbs.length; ++i)\n newLimbs[i] = r.limbs[i];\n newLimbs[i] = carry;\n r.limbs = newLimbs;\n }\n }\n\n function limb(bigint memory a, uint index) internal pure returns (uint) {\n return index < a.limbs.length ? a.limbs[index] : 0;\n }\n\n function max(uint a, uint b) private pure returns (uint) {\n return a > b ? a : b;\n }\n }\n\n contract C {\n using BigInt for bigint;\n\n function f() public pure {\n bigint memory x = BigInt.fromUint(7);\n bigint memory y = BigInt.fromUint(type(uint).max);\n bigint memory z = x.add(y);\n assert(z.limb(1) > 0);\n }\n }\n\nIt is possible to obtain the address of a library by converting\nthe library type to the ``address`` type, i.e. using ``address(LibraryName)``.\n\nAs the compiler does not know the address where the library will be deployed, the compiled hex code\nwill contain placeholders of the form ``__$30bbc0abd4d6364515865950d3e0d10953$__`` `(format was different `_. The placeholder\nis a 34 character prefix of the hex encoding of the keccak256 hash of the fully qualified library\nname, which would be for example ``libraries/bigint.sol:BigInt`` if the library was stored in a file\ncalled ``bigint.sol`` in a ``libraries/`` directory. Such bytecode is incomplete and should not be\ndeployed. Placeholders need to be replaced with actual addresses. You can do that by either passing\nthem to the compiler when the library is being compiled or by using the linker to update an already\ncompiled binary. See :ref:`library-linking` for information on how to use the commandline compiler\nfor linking.\n\nIn comparison to contracts, libraries are restricted in the following ways:\n\n- they cannot have state variables\n- they cannot inherit nor be inherited\n- they cannot receive Ether\n- they cannot be destroyed\n\n(These might be lifted at a later point.)\n\n.. _library-selectors:\n.. index:: ! selector; of a library function\n\nFunction Signatures and Selectors in Libraries\n==============================================\n\nWhile external calls to public or external library functions are possible, the calling convention for such calls\nis considered to be internal to Solidity and not the same as specified for the regular :ref:`contract ABI`.\nExternal library functions support more argument types than external contract functions, for example recursive structs\nand storage pointers. For that reason, the function signatures used to compute the 4-byte selector are computed\nfollowing an internal naming schema and arguments of types not supported in the contract ABI use an internal encoding.\n\nThe following identifiers are used for the types in the signatures:\n\n- Value types, non-storage ``string`` and non-storage ``bytes`` use the same identifiers as in the contract ABI.\n- Non-storage array types follow the same convention as in the contract ABI, i.e. ``[]`` for dynamic arrays and\n ``[M]`` for fixed-size arrays of ``M`` elements.\n- Non-storage structs are referred to by their fully qualified name, i.e. ``C.S`` for ``contract C { struct S { ... } }``.\n- Storage pointer mappings use ``mapping( => ) storage`` where ```` and ```` are\n the identifiers for the key and value types of the mapping, respectively.\n- Other storage pointer types use the type identifier of their corresponding non-storage type, but append a single space\n followed by ``storage`` to it.\n\nThe argument encoding is the same as for the regular contract ABI, except for storage pointers, which are encoded as a\n``uint256`` value referring to the storage slot to which they point.\n\nSimilarly to the contract ABI, the selector consists of the first four bytes of the Keccak256-hash of the signature.\nIts value can be obtained from Solidity using the ``.selector`` member as follows:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.14 <0.9.0;\n\n library L {\n function f(uint256) external {}\n }\n\n contract C {\n function g() public pure returns (bytes4) {\n return L.f.selector;\n }\n }\n\n\n\n.. _call-protection:\n\nCall Protection For Libraries\n=============================\n\nAs mentioned in the introduction, if a library's code is executed\nusing a ``CALL`` instead of a ``DELEGATECALL`` or ``CALLCODE``,\nit will revert unless a ``view`` or ``pure`` function is called.\n\nThe EVM does not provide a direct way for a contract to detect\nwhether it was called using ``CALL`` or not, but a contract\ncan use the ``ADDRESS`` opcode to find out \"where\" it is\ncurrently running. The generated code compares this address\nto the address used at construction time to determine the mode\nof calling.\n\nMore specifically, the runtime code of a library always starts\nwith a push instruction, which is a zero of 20 bytes at\ncompilation time. When the deploy code runs, this constant\nis replaced in memory by the current address and this\nmodified code is stored in the contract. At runtime,\nthis causes the deploy time address to be the first\nconstant to be pushed onto the stack and the dispatcher\ncode compares the current address against this constant\nfor any non-view and non-pure function.\n\nThis means that the actual code stored on chain for a library\nis different from the code reported by the compiler as\n``deployedBytecode``.\n" }, { "path": "docs/contracts/transient-storage.rst", "content": ".. index:: ! transient storage, ! transient, tstore, tload\n\n.. _transient-storage:\n\n*****************\nTransient Storage\n*****************\n\nTransient storage is another data location besides memory, storage, calldata\n(and return-data and code) which was introduced alongside its respective opcodes\n``TSTORE`` and ``TLOAD`` by `EIP-1153 `_.\nThis new data location behaves as a key-value store similar to storage with the main\ndifference being that data in transient storage is not permanent, but is scoped to\nthe current transaction only, after which it will be reset to zero.\nSince the content of transient storage has very limited lifetime and size,\nit does not need to be stored permanently as a part of state\nand the associated gas costs are much lower than in case of storage.\nEVM version ``cancun`` or newer is required for transient storage to be available.\n\nTransient storage variables cannot be initialized in place, i.e., they cannot be assigned\nto upon declaration, since the value would be cleared at the end of the creation transaction,\nrendering the initialization ineffective.\nTransient variables will be :ref:`default value` initialized depending on\ntheir underlying type.\n``constant`` and ``immutable`` variables conflict with transient storage, since\ntheir values are either inlined or directly stored in code.\n\nTransient storage variables have completely independent address space from storage,\nso that the order of transient state variables does not affect the layout of storage\nstate variables and vice-versa.\nThey do need distinct names though because all state variables share the same namespace.\nIt is also important to note that the values in transient storage are packed in the\nsame fashion as those in persistent storage.\nSee :ref:`Storage Layout ` for more information.\n\nBesides that, transient variables can have visibility as well and ``public`` ones will\nhave a getter function generated automatically as usual.\n\nNote that, currently, such use of ``transient`` as a data location is only allowed for\n:ref:`value type ` state variable declarations.\nReference types, such as arrays, mappings and structs, as well as local or parameter\nvariables are not yet supported.\n\nAn expected canonical use case for transient storage is cheaper reentrancy locks,\nwhich can be readily implemented with the opcodes as showcased next.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.28;\n\n contract Generosity {\n mapping(address => bool) sentGifts;\n bool transient locked;\n\n modifier nonReentrant {\n require(!locked, \"Reentrancy attempt\");\n locked = true;\n _;\n // Unlocks the guard, making the pattern composable.\n // After the function exits, it can be called again, even in the same transaction.\n locked = false;\n }\n\n function claimGift() nonReentrant public {\n require(address(this).balance >= 1 ether);\n require(!sentGifts[msg.sender]);\n (bool success, ) = msg.sender.call{value: 1 ether}(\"\");\n require(success);\n\n // In a reentrant function, doing this last would open up the vulnerability\n sentGifts[msg.sender] = true;\n }\n }\n\nTransient storage is private to the contract that owns it, in the same way as persistent storage.\nOnly owning contract frames may access their transient storage, and when they do, all the frames access the same transient store.\n\nTransient storage is part of the EVM state and is subject to the same mutability enforcements\nas persistent storage. As such, any read access to it is not ``pure`` and writing access is not ``view``.\n\nIf the ``TSTORE`` opcode is called within the context of a ``STATICCALL``,\nit will result in an exception instead of performing the modification.\n``TLOAD`` is allowed within the context of a ``STATICCALL``.\n\nWhen transient storage is used in the context of ``DELEGATECALL`` or ``CALLCODE``,\nthen the owning contract of the transient storage is the contract that issued ``DELEGATECALL``\nor ``CALLCODE`` instruction (the caller) as with persistent storage.\nWhen transient storage is used in the context of ``CALL`` or ``STATICCALL``,\nthen the owning contract of the transient storage is the contract that is the target\nof the ``CALL`` or ``STATICCALL`` instruction (the callee).\n\n.. note::\n In the case of ``DELEGATECALL``, since references to transient storage variables\n are currently not supported, it is not possible to pass those into library calls.\n In libraries, access to transient storage is only possible using inline assembly.\n\nIf a frame reverts, all writes to transient storage that took place between entry\nto the frame and the return are reverted, including those that took place in inner calls.\nThe caller of an external call may employ a ``try ... catch`` block to prevent reverts\nbubbling up from the inner calls.\n\n*********************************************************************\nComposability of Smart Contracts and the Caveats of Transient Storage\n*********************************************************************\n\nGiven the caveats mentioned in the specification of EIP-1153,\nin order to preserve the composability of your smart contract,\nutmost care is recommended for more advanced use cases of transient storage.\n\nFor smart contracts, composability is a very important design principle to achieve self-contained behaviour,\nsuch that multiple calls into individual smart contracts can be composed to more complex applications.\nSo far the EVM largely guaranteed composable behaviour, since multiple calls into a smart contract\nwithin a complex transaction are virtually indistinguishable from multiple calls to the contract\nstretched over several transactions. However, transient storage allows a violation of this principle,\nand incorrect use may lead to complex bugs that only surface when used across several calls.\n\nLet's illustrate the problem with a simple example:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.28;\n\n contract MulService {\n uint transient multiplier;\n function setMultiplier(uint mul) external {\n multiplier = mul;\n }\n\n function multiply(uint value) external view returns (uint) {\n return value * multiplier;\n }\n }\n\nand a sequence of external calls:\n\n.. code-block:: solidity\n\n setMultiplier(42);\n multiply(1);\n multiply(2);\n\nIf the example used memory or storage to store the multiplier, it would be fully composable.\nIt would not matter whether you split the sequence into separate transactions or grouped them in some way.\nYou would always get the same result: after ``multiplier`` is set to ``42``, the subsequent calls\nwould return ``42`` and ``84`` respectively.\nThis enables use cases such as batching calls from multiple transactions\ntogether to reduce gas costs.\nTransient storage potentially breaks such use cases since composability can no longer be taken for granted.\nIn the example, if the calls are not executed in the same transaction, then ``multiplier``\nis reset and the next calls to function ``multiply`` would always return ``0``.\n\nAs another example, since transient storage is constructed as a relatively cheap key-value store,\na smart contract author may be tempted to use transient storage as a replacement for in-memory mappings\nwithout keeping track of the modified keys in the mapping and thereby without clearing the mapping\nat the end of the call.\nThis, however, can easily lead to unexpected behaviour in complex transactions,\nin which values set by a previous call into the contract within the same transaction remain.\n\nThe use of transient storage for reentrancy locks that are cleared at the end of the call frame\ninto the contract, is safe.\nHowever, be sure to resist the temptation to save the 100 gas used for resetting the\nreentrancy lock, since failing to do so, will restrict your contract to only one call\nwithin a transaction, preventing its use in complex composed transactions,\nwhich have been a cornerstone for complex applications on chain.\n\nIt is recommend to generally always clear transient storage completely at the end of a call\ninto your smart contract to avoid these kinds of issues and to simplify\nthe analysis of the behaviour of your contract within complex transactions.\nCheck the `Security Considerations section of EIP-1153 `_\nfor further details." }, { "path": "docs/contracts/using-for.rst", "content": ".. index:: ! using for, library, ! operator;user-defined, function;free\n\n.. _using-for:\n\n*********\nUsing For\n*********\n\nThe directive ``using A for B`` can be used to attach\nfunctions (``A``) as operators to user-defined value types\nor as member functions to any type (``B``).\nThe member functions receive the object they are called on\nas their first parameter (like the ``self`` variable in Python).\nThe operator functions receive operands as parameters.\n\nIt is valid either at file level or inside a contract,\nat contract level.\n\nThe first part, ``A``, can be one of:\n\n- A list of functions, optionally with an operator name assigned (e.g.\n ``using {f, g as +, h, L.t} for uint``).\n If no operator is specified, the function can be either a library function or a free function and\n is attached to the type as a member function.\n Otherwise it must be a free function and it becomes the definition of that operator on the type.\n- The name of a library (e.g. ``using L for uint``) -\n all non-private functions of the library are attached to the type\n as member functions\n\nAt file level, the second part, ``B``, has to be an explicit type (without data location specifier).\nInside contracts, you can also use ``*`` in place of the type (e.g. ``using L for *;``),\nwhich has the effect that all functions of the library ``L``\nare attached to *all* types.\n\nIf you specify a library, *all* non-private functions in the library get attached,\neven those where the type of the first parameter does not\nmatch the type of the object. The type is checked at the\npoint the function is called and function overload\nresolution is performed.\n\nIf you use a list of functions (e.g. ``using {f, g, h, L.t} for uint``),\nthen the type (``uint``) has to be implicitly convertible to the\nfirst parameter of each of these functions. This check is\nperformed even if none of these functions are called.\nNote that private library functions can only be specified when ``using for`` is inside a library.\n\nIf you define an operator (e.g. ``using {f as +} for T``), then the type (``T``) must be a\n:ref:`user-defined value type ` and the definition must be a ``pure`` function.\nOperator definitions must be global.\nThe following operators can be defined this way:\n\n+------------+----------+---------------------------------------------+\n| Category | Operator | Possible signatures |\n+============+==========+=============================================+\n| Bitwise | ``&`` | ``function (T, T) pure returns (T)`` |\n| +----------+---------------------------------------------+\n| | ``|`` | ``function (T, T) pure returns (T)`` |\n| +----------+---------------------------------------------+\n| | ``^`` | ``function (T, T) pure returns (T)`` |\n| +----------+---------------------------------------------+\n| | ``~`` | ``function (T) pure returns (T)`` |\n+------------+----------+---------------------------------------------+\n| Arithmetic | ``+`` | ``function (T, T) pure returns (T)`` |\n| +----------+---------------------------------------------+\n| | ``-`` | ``function (T, T) pure returns (T)`` |\n| + +---------------------------------------------+\n| | | ``function (T) pure returns (T)`` |\n| +----------+---------------------------------------------+\n| | ``*`` | ``function (T, T) pure returns (T)`` |\n| +----------+---------------------------------------------+\n| | ``/`` | ``function (T, T) pure returns (T)`` |\n| +----------+---------------------------------------------+\n| | ``%`` | ``function (T, T) pure returns (T)`` |\n+------------+----------+---------------------------------------------+\n| Comparison | ``==`` | ``function (T, T) pure returns (bool)`` |\n| +----------+---------------------------------------------+\n| | ``!=`` | ``function (T, T) pure returns (bool)`` |\n| +----------+---------------------------------------------+\n| | ``<`` | ``function (T, T) pure returns (bool)`` |\n| +----------+---------------------------------------------+\n| | ``<=`` | ``function (T, T) pure returns (bool)`` |\n| +----------+---------------------------------------------+\n| | ``>`` | ``function (T, T) pure returns (bool)`` |\n| +----------+---------------------------------------------+\n| | ``>=`` | ``function (T, T) pure returns (bool)`` |\n+------------+----------+---------------------------------------------+\n\nNote that unary and binary ``-`` need separate definitions.\nThe compiler will choose the right definition based on how the operator is invoked.\n\nThe ``using A for B;`` directive is active only within the current\nscope (either the contract or the current module/source unit),\nincluding within all of its functions, and has no effect\noutside of the contract or module in which it is used.\n\nWhen the directive is used at file level and applied to a\nuser-defined type which was defined at file level in the same file,\nthe word ``global`` can be added at the end. This will have the\neffect that the functions and operators are attached to the type everywhere\nthe type is available (including other files), not only in the\nscope of the using statement.\n\nLet us rewrite the set example from the\n:ref:`libraries` section in this way, using file-level functions\ninstead of library functions.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.13;\n\n struct Data { mapping(uint => bool) flags; }\n // Now we attach functions to the type.\n // The attached functions can be used throughout the rest of the module.\n // If you import the module, you have to\n // repeat the using directive there, for example as\n // import \"flags.sol\" as Flags;\n // using {Flags.insert, Flags.remove, Flags.contains}\n // for Flags.Data;\n using {insert, remove, contains} for Data;\n\n function insert(Data storage self, uint value)\n returns (bool)\n {\n if (self.flags[value])\n return false; // already there\n self.flags[value] = true;\n return true;\n }\n\n function remove(Data storage self, uint value)\n returns (bool)\n {\n if (!self.flags[value])\n return false; // not there\n self.flags[value] = false;\n return true;\n }\n\n function contains(Data storage self, uint value)\n view\n returns (bool)\n {\n return self.flags[value];\n }\n\n\n contract C {\n Data knownValues;\n\n function register(uint value) public {\n // Here, all variables of type Data have\n // corresponding member functions.\n // The following function call is identical to\n // `Set.insert(knownValues, value)`\n require(knownValues.insert(value));\n }\n }\n\nIt is also possible to extend built-in types in that way.\nIn this example, we will use a library.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.13;\n\n library Search {\n function indexOf(uint[] storage self, uint value)\n public\n view\n returns (uint)\n {\n for (uint i = 0; i < self.length; i++)\n if (self[i] == value) return i;\n return type(uint).max;\n }\n }\n using Search for uint[];\n\n contract C {\n uint[] data;\n\n function append(uint value) public {\n data.push(value);\n }\n\n function replace(uint from, uint to) public {\n // This performs the library function call\n uint index = data.indexOf(from);\n if (index == type(uint).max)\n data.push(to);\n else\n data[index] = to;\n }\n }\n\nNote that all external library calls are actual EVM function calls. This means that\nif you pass memory or value types, a copy will be performed, even in case of the\n``self`` variable. The only situation where no copy will be performed\nis when storage reference variables are used or when internal library\nfunctions are called.\n\nAnother example shows how to define a custom operator for a user-defined type:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.19;\n\n type UFixed16x2 is uint16;\n\n using {\n add as +,\n div as /\n } for UFixed16x2 global;\n\n uint32 constant SCALE = 100;\n\n function add(UFixed16x2 a, UFixed16x2 b) pure returns (UFixed16x2) {\n return UFixed16x2.wrap(UFixed16x2.unwrap(a) + UFixed16x2.unwrap(b));\n }\n\n function div(UFixed16x2 a, UFixed16x2 b) pure returns (UFixed16x2) {\n uint32 a32 = UFixed16x2.unwrap(a);\n uint32 b32 = UFixed16x2.unwrap(b);\n uint32 result32 = a32 * SCALE / b32;\n require(result32 <= type(uint16).max, \"Divide overflow\");\n return UFixed16x2.wrap(uint16(a32 * SCALE / b32));\n }\n\n contract Math {\n function avg(UFixed16x2 a, UFixed16x2 b) public pure returns (UFixed16x2) {\n return (a + b) / UFixed16x2.wrap(200);\n }\n }\n" }, { "path": "docs/contracts/visibility-and-getters.rst", "content": ".. index:: ! visibility, external, public, private, internal\n\n.. |visibility-caveat| replace:: Making something ``private`` or ``internal`` only prevents other contracts from reading or modifying the information, but it will still be visible to the whole world outside of the blockchain.\n\n.. _visibility-and-getters:\n\n**********************\nVisibility and Getters\n**********************\n\nState Variable Visibility\n=========================\n\n``public``\n Public state variables differ from internal ones only in that the compiler automatically generates\n :ref:`getter functions` for them, which allows other contracts to read their values.\n When used within the same contract, the external access (e.g. ``this.x``) invokes the getter\n while internal access (e.g. ``x``) gets the variable value directly from storage.\n Setter functions are not generated so other contracts cannot directly modify their values.\n\n``internal``\n Internal state variables can only be accessed from within the contract they are defined in\n and in derived contracts.\n They cannot be accessed externally.\n This is the default visibility level for state variables.\n\n``private``\n Private state variables are like internal ones but they are not visible in derived contracts.\n\n.. warning::\n |visibility-caveat|\n\nFunction Visibility\n===================\n\nSolidity knows two kinds of function calls: external ones that do create an actual EVM message call and internal ones that do not.\nFurthermore, internal functions can be made inaccessible to derived contracts.\nThis gives rise to four types of visibility for functions.\n\n``external``\n External functions are part of the contract interface,\n which means they can be called from other contracts and\n via transactions. An external function ``f`` cannot be called\n internally (i.e. ``f()`` does not work, but ``this.f()`` works).\n\n``public``\n Public functions are part of the contract interface\n and can be either called internally or via message calls.\n\n``internal``\n Internal functions can only be accessed from within the current contract\n or contracts deriving from it.\n They cannot be accessed externally.\n Since they are not exposed to the outside through the contract's ABI, they can take parameters of internal types like mappings or storage references.\n\n``private``\n Private functions are like internal ones but they are not visible in derived contracts.\n\n.. warning::\n |visibility-caveat|\n\nThe visibility specifier is given after the type for\nstate variables and between parameter list and\nreturn parameter list for functions.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract C {\n function f(uint a) private pure returns (uint b) { return a + 1; }\n function setData(uint a) internal { data = a; }\n uint public data;\n }\n\nIn the following example, ``D``, can call ``c.getData()`` to retrieve the value of\n``data`` in state storage, but is not able to call ``f``. Contract ``E`` is derived from\n``C`` and, thus, can call ``compute``.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract C {\n uint private data;\n\n function f(uint a) private pure returns(uint b) { return a + 1; }\n function setData(uint a) public { data = a; }\n function getData() public view returns(uint) { return data; }\n function compute(uint a, uint b) internal pure returns (uint) { return a + b; }\n }\n\n // This will not compile\n contract D {\n function readData() public {\n C c = new C();\n uint local = c.f(7); // error: member `f` is not visible\n c.setData(3);\n local = c.getData();\n local = c.compute(3, 5); // error: member `compute` is not visible\n }\n }\n\n contract E is C {\n function g() public {\n C c = new C();\n uint val = compute(3, 5); // access to internal member (from derived to parent contract)\n }\n }\n\n.. index:: ! getter;function, ! function;getter\n.. _getter-functions:\n\nGetter Functions\n================\n\nThe compiler automatically creates getter functions for\nall **public** state variables. For the contract given below, the compiler will\ngenerate a function called ``data`` that does not take any\narguments and returns a ``uint``, the value of the state\nvariable ``data``. State variables can be initialized\nwhen they are declared.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract C {\n uint public data = 42;\n }\n\n contract Caller {\n C c = new C();\n function f() public view returns (uint) {\n return c.data();\n }\n }\n\nThe getter functions have external visibility. If the\nsymbol is accessed internally (i.e. without ``this.``),\nit evaluates to a state variable. If it is accessed externally\n(i.e. with ``this.``), it evaluates to a function.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.0 <0.9.0;\n\n contract C {\n uint public data;\n function x() public returns (uint) {\n data = 3; // internal access\n return this.data(); // external access\n }\n }\n\nIf you have a ``public`` state variable of array type, then you can only retrieve\nsingle elements of the array via the generated getter function. This mechanism\nexists to avoid high gas costs when returning an entire array. You can use\narguments to specify which individual element to return, for example\n``myArray(0)``. If you want to return an entire array in one call, then you need\nto write a function, for example:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract arrayExample {\n // public state variable\n uint[] public myArray;\n\n // Getter function generated by the compiler\n /*\n function myArray(uint i) public view returns (uint) {\n return myArray[i];\n }\n */\n\n // function that returns entire array\n function getArray() public view returns (uint[] memory) {\n return myArray;\n }\n }\n\nNow you can use ``getArray()`` to retrieve the entire array, instead of\n``myArray(i)``, which returns a single element per call.\n\nThe next example is more complex:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.0 <0.9.0;\n\n contract Complex {\n struct Data {\n uint a;\n bytes3 b;\n mapping(uint => uint) map;\n uint[3] c;\n uint[] d;\n bytes e;\n }\n mapping(uint => mapping(bool => Data[])) public data;\n }\n\nIt generates a function of the following form. The mapping and arrays (with the\nexception of byte arrays) in the struct are omitted because there is no good way\nto select individual struct members or provide a key for the mapping:\n\n.. code-block:: solidity\n\n function data(uint arg1, bool arg2, uint arg3)\n public\n returns (uint a, bytes3 b, bytes memory e)\n {\n a = data[arg1][arg2][arg3].a;\n b = data[arg1][arg2][arg3].b;\n e = data[arg1][arg2][arg3].e;\n }\n" }, { "path": "docs/contracts.rst", "content": ".. index:: ! contract\n\n.. _contracts:\n\n##########\nContracts\n##########\n\nContracts in Solidity are similar to classes in object-oriented languages. They\ncontain persistent data in state variables, and functions that can modify these\nvariables. Calling a function on a different contract (instance) will perform\nan EVM function call and thus switch the context such that state variables\nin the calling contract are\ninaccessible. A contract and its functions need to be called for anything to happen.\nThere is no \"cron\" concept in Ethereum to call a function at a particular event automatically.\n\n.. include:: contracts/creating-contracts.rst\n\n.. include:: contracts/visibility-and-getters.rst\n\n.. include:: contracts/function-modifiers.rst\n\n.. include:: contracts/transient-storage.rst\n\n.. include:: contracts/constant-state-variables.rst\n.. include:: contracts/custom-storage-layout.rst\n.. include:: contracts/functions.rst\n\n.. include:: contracts/events.rst\n.. include:: contracts/errors.rst\n\n.. include:: contracts/inheritance.rst\n\n.. include:: contracts/abstract-contracts.rst\n.. include:: contracts/interfaces.rst\n\n.. include:: contracts/libraries.rst\n\n.. include:: contracts/using-for.rst" }, { "path": "docs/contributing.rst", "content": "############\nContributing\n############\n\nHelp is always welcome and there are plenty of options to contribute to Solidity.\n\nIn particular, we appreciate support in the following areas:\n\n* Reporting issues.\n* Fixing and responding to `Solidity's GitHub issues\n `_, especially those tagged as\n `\"good first issue\" `_ which are\n meant as introductory issues for external contributors.\n* Improving the documentation.\n* `Translating `_ the documentation into more languages.\n* Responding to questions from other users on `StackExchange\n `_ and the `Solidity Gitter Chat\n `_.\n* Getting involved in the language design process by proposing language changes or new features in the `Solidity forum `_ and providing feedback.\n\nTo get started, you can try :ref:`building-from-source` in order to familiarize\nyourself with the components of Solidity and the build process. Also, it may be\nuseful to become well-versed at writing smart-contracts in Solidity.\n\nPlease note that this project is released with a `Contributor Code of Conduct `_. By participating in this project — in the issues, pull requests, or Gitter channels — you agree to abide by its terms.\n\nTeam Calls\n==========\n\nIf you have issues or pull requests to discuss, or are interested in hearing what\nthe team and contributors are working on, you can join our public team call:\n\n- Wednesdays at 3PM CET/CEST.\n\nThe call takes place on `Jitsi `_.\n\nNew topics can be freely added to the `agenda `_\nand will be scheduled for discussion on the nearest call.\n\nHow to Report Issues\n====================\n\nTo report an issue, please use the\n`GitHub issues tracker `_. When\nreporting issues, please mention the following details:\n\n* Solidity version.\n* Source code (if applicable).\n* Operating system.\n* Steps to reproduce the issue.\n* Actual vs. expected behavior.\n\nReducing the source code that caused the issue to a bare minimum is always\nvery helpful, and sometimes even clarifies a misunderstanding.\n\nFor technical discussions about language design, a post in the\n`Solidity forum `_ is the correct place (see :ref:`solidity_language_design`).\n\nWorkflow for Pull Requests\n==========================\n\nIn order to contribute, please fork off of the ``develop`` branch and make your\nchanges there. Your commit messages should detail *why* you made your change\nin addition to *what* you did (unless it is a tiny change).\n\nIf you need to pull in any changes from ``develop`` after making your fork (for\nexample, to resolve potential merge conflicts), please avoid using ``git merge``\nand instead, ``git rebase`` your branch. This will help us review your change\nmore easily.\n\nAdditionally, if you are writing a new feature, please ensure you add appropriate\ntest cases under ``test/`` (see below).\n\nHowever, if you are making a larger change, please consult with the `Solidity Development Gitter channel\n`_ (different from the one mentioned above — this one is\nfocused on compiler and language development instead of language usage) first.\n\nNew features and bugfixes should be added to the ``Changelog.md`` file: please\nfollow the style of previous entries, when applicable.\n\nFinally, please make sure you respect the `coding style\n`_\nfor this project. Also, even though we do CI testing, please test your code and\nensure that it builds locally before submitting a pull request.\n\nWe highly recommend going through our `review checklist `_ before submitting the pull request.\nWe 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.\n\nThank you for your help!\n\nRunning the Compiler Tests\n==========================\n\nPrerequisites\n-------------\n\nFor running all compiler tests you may want to optionally install a few\ndependencies (`evmone `_,\n`z3 `_, `Eldarica `_,\n`cvc5 `).\n\nOn macOS systems, some of the testing scripts expect GNU coreutils to be installed.\nThis can be easiest accomplished using Homebrew: ``brew install coreutils``.\n\nOn Windows systems, make sure that you have a privilege to create symlinks,\notherwise several tests may fail.\nAdministrators should have that privilege, but you may also\n`grant it to other users `_\nor\n`enable Developer Mode `_.\n\nRunning the Tests\n-----------------\n\nSolidity includes different types of tests, most of them bundled into the\n`Boost C++ Test Framework `_ application ``soltest``.\nRunning ``build/test/soltest`` or its wrapper ``scripts/soltest.sh`` is sufficient for most changes.\n\nThe ``./scripts/tests.sh`` script executes most Solidity tests automatically,\nincluding those bundled into the `Boost C++ Test Framework `_\napplication ``soltest`` (or its wrapper ``scripts/soltest.sh``), as well as command-line tests and\ncompilation tests.\n\nThe test system automatically tries to discover the location of\nthe `evmone `_ for running the semantic tests.\n\nThe ``evmone`` library must be located in the ``deps`` or ``deps/lib`` directory relative to the\ncurrent working directory, to its parent or its parent's parent. Alternatively, an explicit location\nfor the ``evmone`` shared object can be specified via the ``ETH_EVMONE`` environment variable.\n\n``evmone`` is needed mainly for running semantic and gas tests.\nIf you do not have it installed, you can skip these tests by passing the ``--no-semantic-tests``\nflag to ``scripts/soltest.sh``.\n\nThe ``evmone`` library should end with the file name\nextension ``.so`` on Linux, ``.dll`` on Windows systems and ``.dylib`` on macOS.\n\nFor running SMT tests, the ``z3`` executable must be present in ``PATH``.\nA few SMT tests use ``Eldarica`` instead of ``z3``.\nThese require its executable (``eld``) to be present in ``PATH`` for the tests to pass.\nHowever, if ``Eldarica`` is not found, these tests will be automatically skipped.\n\nIf ``z3`` is not present on your system, you should disable the\nSMT tests by exporting ``SMT_FLAGS=--no-smt`` before running ``./scripts/tests.sh`` or\nrunning ``./scripts/soltest.sh --no-smt``.\nThese tests are ``libsolidity/smtCheckerTests``.\n\n.. note::\n\n To get a list of all unit tests run by Soltest, run ``./build/test/soltest --list_content=HRF``.\n\nFor quicker results you can run a subset of, or specific tests.\n\nTo run a subset of tests, you can use filters:\n``./scripts/soltest.sh -t TestSuite/TestName``,\nwhere ``TestName`` can be a wildcard ``*``.\n\nOr, for example, to run all the tests for the yul disambiguator:\n``./scripts/soltest.sh -t \"yulOptimizerTests/disambiguator/*\" --no-smt``.\n\n``./build/test/soltest --help`` has extensive help on all of the options available.\n\nSee especially:\n\n- `show_progress (-p) `_ to show test completion,\n- `run_test (-t) `_ to run specific tests cases, and\n- `report-level (-r) `_ give a more detailed report.\n\n.. note::\n\n Those working in a Windows environment wanting to run the above basic sets\n without z3. Using Git Bash, you use: ``./build/test/Release/soltest.exe -- --no-smt``.\n If you are running this in plain Command Prompt, use ``.\\build\\test\\Release\\soltest.exe -- --no-smt``.\n\nIf you want to debug using GDB, make sure you build differently than the \"usual\".\nFor example, you could run the following command in your ``build`` folder:\n\n.. code-block:: bash\n\n cmake -DCMAKE_BUILD_TYPE=Debug ..\n make\n\nThis creates symbols so that when you debug a test using the ``--debug`` flag,\nyou have access to functions and variables in which you can break or print with.\n\nThe CI runs additional tests (including ``solc-js`` and testing third party Solidity\nframeworks) that require compiling the Emscripten target.\n\nWriting and Running Syntax Tests\n--------------------------------\n\nSyntax tests check that the compiler generates the correct error messages for invalid code\nand properly accepts valid code.\nThey are stored in individual files inside the ``tests/libsolidity/syntaxTests`` folder.\nThese files must contain annotations, stating the expected result(s) of the respective test.\nThe test suite compiles and checks them against the given expectations.\n\nFor example: ``./test/libsolidity/syntaxTests/double_stateVariable_declaration.sol``\n\n.. code-block:: solidity\n\n contract test {\n uint256 variable;\n uint128 variable;\n }\n // ----\n // DeclarationError: (36-52): Identifier already declared.\n\nA syntax test must contain at least the contract under test itself, followed by the separator ``// ----``. The comments that follow the separator are used to describe the\nexpected compiler errors or warnings. The number range denotes the location in the source where the error occurred.\nIf you want the contract to compile without any errors or warning you can leave\nout the separator and the comments that follow it.\n\nIn the above example, the state variable ``variable`` was declared twice, which is not allowed. This results in a ``DeclarationError`` stating that the identifier was already declared.\n\nThe ``isoltest`` tool is used for these tests and you can find it under ``./build/test/tools/``. It is an interactive tool which allows\nediting of failing contracts using your preferred text editor. Let's try to break this test by removing the second declaration of ``variable``:\n\n.. code-block:: solidity\n\n contract test {\n uint256 variable;\n }\n // ----\n // DeclarationError: (36-52): Identifier already declared.\n\nRunning ``./build/test/tools/isoltest`` again results in a test failure:\n\n.. code-block:: text\n\n syntaxTests/double_stateVariable_declaration.sol: FAIL\n Contract:\n contract test {\n uint256 variable;\n }\n\n Expected result:\n DeclarationError: (36-52): Identifier already declared.\n Obtained result:\n Success\n\n\n``isoltest`` prints the expected result next to the obtained result, and also\nprovides a way to edit, update or skip the current contract file, or quit the application.\n\nIt offers several options for failing tests:\n\n- ``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).\n- ``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.\n- ``skip``: Skips the execution of this particular test.\n- ``quit``: Quits ``isoltest``.\n\nAll of these options apply to the current contract, except ``quit`` which stops the entire testing process.\n\nAutomatically updating the test above changes it to\n\n.. code-block:: solidity\n\n contract test {\n uint256 variable;\n }\n // ----\n\nand re-run the test. It now passes again:\n\n.. code-block:: text\n\n Re-running test case...\n syntaxTests/double_stateVariable_declaration.sol: OK\n\n\n.. note::\n\n Choose a name for the contract file that explains what it tests, e.g. ``double_variable_declaration.sol``.\n Do not put more than one contract into a single file, unless you are testing inheritance or cross-contract calls.\n Each file should test one aspect of your new feature.\n\nCommand-line Tests\n------------------\n\nOur suite of end-to-end command-line tests checks the behaviour of the compiler binary as a whole\nin various scenarios.\nThese tests are located in `test/cmdlineTests/ `_,\none per subdirectory, and can be executed using the ``cmdlineTests.sh`` script.\n\nBy default the script runs all available tests.\nYou can also provide one or more `file name patterns `_,\nin which case only the tests matching at least one pattern will be executed.\nIt is also possible to exclude files matching a specific pattern by prefixing it with ``--exclude``.\n\nBy default the script assumes that a ``solc`` binary is available inside the ``build/`` subdirectory\ninside the working copy.\nIf you build the compiler outside of the source tree, you can use the ``SOLIDITY_BUILD_DIR`` environment\nvariable to specify a different location for the build directory.\n\nExample:\n\n.. code-block:: bash\n\n export SOLIDITY_BUILD_DIR=~/solidity/build/\n test/cmdlineTests.sh \"standard_*\" \"*_yul_*\" --exclude \"standard_yul_*\"\n\nThe commands above will run tests from directories starting with ``test/cmdlineTests/standard_`` and\nsubdirectories of ``test/cmdlineTests/`` that have ``_yul_`` somewhere in the name,\nbut no test whose name starts with ``standard_yul_`` will be executed.\nIt will also assume that the file ``solidity/build/solc/solc`` inside your home directory is the\ncompiler binary (unless you are on Windows -- then ``solidity/build/solc/Release/solc.exe``).\n\nThere are several kinds of command-line tests:\n\n- *Standard JSON test*: contains at least an ``input.json`` file.\n In general may contain:\n\n - ``input.json``: input file to be passed to the ``--standard-json`` option on the command line.\n - ``output.json``: expected Standard JSON output.\n - ``args``: extra command-line arguments passed to ``solc``.\n\n- *CLI test*: contains at least an ``input.*`` file (other than ``input.json``).\n In general may contain:\n\n - ``input.*``: a single input file, whose name will be supplied to ``solc`` on the command line.\n Usually ``input.sol`` or ``input.yul``.\n - ``args``: extra command-line arguments passed to ``solc``.\n - ``stdin``: content to be passed to ``solc`` via standard input.\n - ``output``: expected content of the standard output.\n - ``err``: expected content of the standard error output.\n - ``exit``: expected exit code. If not provided, zero is expected.\n\n- *Script test*: contains a ``test.*`` file.\n In general may contain:\n\n - ``test.*``: a single script to run, usually ``test.sh`` or ``test.py``.\n The script must be executable.\n\nRunning the Fuzzer via AFL\n==========================\n\nFuzzing is a technique that runs programs on more or less random inputs to find exceptional execution\nstates (segmentation faults, exceptions, etc). Modern fuzzers are clever and run a directed search\ninside the input. We have a specialized binary called ``solfuzzer`` which takes source code as input\nand fails whenever it encounters an internal compiler error, segmentation fault or similar, but\ndoes not fail if e.g., the code contains an error. This way, fuzzing tools can find internal problems in the compiler.\n\nWe mainly use `AFL `_ for fuzzing. You need to download and\ninstall the AFL packages from your repositories (afl, afl-clang) or build them manually.\nNext, build Solidity (or just the ``solfuzzer`` binary) with AFL as your compiler:\n\n.. code-block:: bash\n\n cd build\n # if needed\n make clean\n cmake .. -DCMAKE_C_COMPILER=path/to/afl-gcc -DCMAKE_CXX_COMPILER=path/to/afl-g++\n make solfuzzer\n\nAt this stage, you should be able to see a message similar to the following:\n\n.. code-block:: text\n\n Scanning dependencies of target solfuzzer\n [ 98%] Building CXX object test/tools/CMakeFiles/solfuzzer.dir/fuzzer.cpp.o\n afl-cc 2.52b by \n afl-as 2.52b by \n [+] Instrumented 1949 locations (64-bit, non-hardened mode, ratio 100%).\n [100%] Linking CXX executable solfuzzer\n\nIf the instrumentation messages did not appear, try switching the cmake flags pointing to AFL's clang binaries:\n\n.. code-block:: bash\n\n # if previously failed\n make clean\n cmake .. -DCMAKE_C_COMPILER=path/to/afl-clang -DCMAKE_CXX_COMPILER=path/to/afl-clang++\n make solfuzzer\n\nOtherwise, upon execution the fuzzer halts with an error saying binary is not instrumented:\n\n.. code-block:: text\n\n afl-fuzz 2.52b by \n ... (truncated messages)\n [*] Validating target binary...\n\n [-] Looks like the target binary is not instrumented! The fuzzer depends on\n compile-time instrumentation to isolate interesting test cases while\n mutating the input data. For more information, and for tips on how to\n instrument binaries, please see /usr/share/doc/afl-doc/docs/README.\n\n When source code is not available, you may be able to leverage QEMU\n mode support. Consult the README for tips on how to enable this.\n (It is also possible to use afl-fuzz as a traditional, \"dumb\" fuzzer.\n For that, you can use the -n option - but expect much worse results.)\n\n [-] PROGRAM ABORT : No instrumentation detected\n Location : check_binary(), afl-fuzz.c:6920\n\n\nNext, you need some example source files. This makes it much easier for the fuzzer\nto find errors. You can either copy some files from the syntax tests or extract test files\nfrom the documentation or the other tests:\n\n.. code-block:: bash\n\n mkdir /tmp/test_cases\n cd /tmp/test_cases\n # extract from tests:\n path/to/solidity/scripts/isolate_tests.py path/to/solidity/test/libsolidity/SolidityEndToEndTest.cpp\n # extract from documentation:\n path/to/solidity/scripts/isolate_tests.py path/to/solidity/docs\n\nThe AFL documentation states that the corpus (the initial input files) should not be\ntoo large. The files themselves should not be larger than 1 kB and there should be\nat most one input file per functionality, so better start with a small number of.\nThere is also a tool called ``afl-cmin`` that can trim input files\nthat result in similar behavior of the binary.\n\nNow run the fuzzer (the ``-m`` extends the size of memory to 60 MB):\n\n.. code-block:: bash\n\n afl-fuzz -m 60 -i /tmp/test_cases -o /tmp/fuzzer_reports -- /path/to/solfuzzer\n\nThe fuzzer creates source files that lead to failures in ``/tmp/fuzzer_reports``.\nOften it finds many similar source files that produce the same error. You can\nuse the tool ``scripts/uniqueErrors.sh`` to filter out the unique errors.\n\nWhiskers\n========\n\n*Whiskers* is a string templating system similar to `Mustache `_. It is used by the\ncompiler in various places to aid readability, and thus maintainability and verifiability, of the code.\n\nThe syntax comes with a substantial difference to Mustache. The template markers ``{{`` and ``}}`` are\nreplaced by ``<`` and ``>`` in order to aid parsing and avoid conflicts with :ref:`yul`\n(The symbols ``<`` and ``>`` are invalid in inline assembly, while ``{`` and ``}`` are used to delimit blocks).\nAnother limitation is that lists are only resolved one depth and they do not recurse. This may change in the future.\n\nA rough specification is the following:\n\nAny occurrence of ```` is replaced by the string-value of the supplied variable ``name`` without any\nescaping and without iterated replacements. An area can be delimited by ``<#name>...``. It is replaced\nby as many concatenations of its contents as there were sets of variables supplied to the template system,\neach time replacing any ```` items by their respective value. Top-level variables can also be used\ninside such areas.\n\nThere are also conditionals of the form ``......``, where template replacements\ncontinue recursively either in the first or the second segment depending on the value of the boolean\nparameter ``name``. If ``......`` is used, then the check is whether\nthe string parameter ``name`` is non-empty.\n\n.. _documentation-style:\n\nDocumentation Style Guide\n=========================\n\nIn the following section you find style recommendations specifically focusing on documentation\ncontributions to Solidity.\n\nEnglish Language\n----------------\n\nUse International English, unless using project or brand names. Try to reduce the usage of\nlocal slang and references, making your language as clear to all readers as possible.\nBelow are some references to help:\n\n* `Simplified technical English `_\n* `International English `_\n\n.. note::\n\n While the official Solidity documentation is written in English, there are community contributed :ref:`translations`\n in other languages available. Please refer to the `translation guide `_\n for information on how to contribute to the community translations.\n\nTitle Case for Headings\n-----------------------\n\nUse `title case `_ for headings. This means capitalise all principal words in\ntitles, but not articles, conjunctions, and prepositions unless they start the\ntitle.\n\nFor example, the following are all correct:\n\n* Title Case for Headings.\n* For Headings Use Title Case.\n* Local and State Variable Names.\n* Order of Layout.\n\nExpand Contractions\n-------------------\n\nUse expanded contractions for words, for example:\n\n* \"Do not\" instead of \"Don't\".\n* \"Can not\" instead of \"Can't\".\n\nActive and Passive Voice\n------------------------\n\nActive voice is typically recommended for tutorial style documentation as it\nhelps the reader understand who or what is performing a task. However, as the\nSolidity documentation is a mixture of tutorials and reference content, passive\nvoice is sometimes more applicable.\n\nAs a summary:\n\n* Use passive voice for technical reference, for example language definition and internals of the Ethereum VM.\n* Use active voice when describing recommendations on how to apply an aspect of Solidity.\n\nFor example, the below is in passive voice as it specifies an aspect of Solidity:\n\n Functions can be declared ``pure`` in which case they promise not to read\n from or modify the state.\n\nFor example, the below is in active voice as it discusses an application of Solidity:\n\n When invoking the compiler, you can specify how to discover the first element\n of a path, and also path prefix remappings.\n\nCommon Terms\n------------\n\n* \"Function parameters\" and \"return variables\", not input and output parameters.\n\nCode Examples\n-------------\n\nA CI process tests all code block formatted code examples that begin with ``pragma solidity``, ``contract``, ``library``\nor ``interface`` using the ``./test/cmdlineTests.sh`` script when you create a PR. If you are adding new code examples,\nensure they work and pass tests before creating the PR.\n\nEnsure that all code examples begin with a ``pragma`` version that spans the largest where the contract code is valid.\nFor example ``pragma solidity >=0.4.0 <0.9.0;``.\n\nRunning Documentation Tests\n---------------------------\n\nMake sure your contributions pass our documentation tests by running ``./docs/docs.sh`` that installs dependencies\nneeded for documentation and checks for any problems such as broken links or syntax issues.\n\n.. _solidity_language_design:\n\nSolidity Language Design\n========================\n\nTo actively get involved in the language design process and to share your ideas concerning the future of Solidity,\nplease join the `Solidity forum `_.\n\nThe Solidity forum serves as the place to propose and discuss new language features and their implementation in\nthe early stages of ideation or modifications of existing features.\n\nAs soon as proposals get more tangible, their\nimplementation will also be discussed in the `Solidity GitHub repository `_\nin the form of issues.\n\nIn addition to the forum and issue discussions, we regularly host language design discussion calls in which selected\ntopics, issues or feature implementations are debated in detail. The invitation to those calls is shared via the forum.\n\nWe are also sharing feedback surveys and other content that is relevant to language design in the forum.\n\nIf you want to know where the team is standing in terms of implementing new features, you can follow the implementation status in the `Solidity GitHub project `_.\nIssues in the design backlog need further specification and will either be discussed in a language design call or in a regular team call. You can\nsee the upcoming changes for the next breaking release by changing from the default branch (`develop`) to the `breaking branch `_.\n\nFor ad-hoc cases and questions, you can reach out to us via the `Solidity-dev Gitter channel `_ — a\ndedicated chatroom for conversations around the Solidity compiler and language development.\n\nWe are happy to hear your thoughts on how we can improve the language design process to be even more collaborative and transparent.\n" }, { "path": "docs/control-structures.rst", "content": "##################################\nExpressions and Control Structures\n##################################\n\n.. index:: ! parameter, parameter;input, parameter;output, function parameter, parameter;function, return variable, variable;return, return\n\n\n.. index:: if, else, while, do/while, for, break, continue, return, switch, goto\n\nControl Structures\n===================\n\nMost of the control structures known from curly-braces languages are available in Solidity:\n\nThere is: ``if``, ``else``, ``while``, ``do``, ``for``, ``break``, ``continue``, ``return``, with\nthe usual semantics known from C or JavaScript.\n\nSolidity also supports exception handling in the form of ``try``/``catch``-statements,\nbut only for :ref:`external function calls ` and\ncontract creation calls. Errors can be created using the :ref:`revert statement `.\n\nParentheses can *not* be omitted for conditionals, but curly braces can be omitted\naround single-statement bodies.\n\nNote that there is no type conversion from non-boolean to boolean types as\nthere is in C and JavaScript, so ``if (1) { ... }`` is *not* valid\nSolidity.\n\n.. index:: ! function;call, function;internal, function;external\n\n.. _function-calls:\n\nFunction Calls\n==============\n\n.. _internal-function-calls:\n\nInternal Function Calls\n-----------------------\n\nFunctions of the current contract can be called directly (\"internally\"), also recursively, as seen in\nthis nonsensical example:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.22 <0.9.0;\n\n // This will report a warning\n contract C {\n function g(uint a) public pure returns (uint ret) { return a + f(); }\n function f() internal pure returns (uint ret) { return g(7) + f(); }\n }\n\nThese function calls are translated into simple jumps inside the EVM. This has\nthe effect that the current memory is not cleared, i.e. passing memory references\nto internally-called functions is very efficient. Only functions of the same\ncontract instance can be called internally.\n\nYou should still avoid excessive recursion, as every internal function call\nuses up at least one stack slot and there are only 1024 slots available.\n\n.. _external-function-calls:\n\nExternal Function Calls\n-----------------------\n\nFunctions can also be called using the ``this.g(8);`` and ``c.g(2);`` notation, where\n``c`` is a contract instance and ``g`` is a function belonging to ``c``.\nCalling the function ``g`` via either way results in it being called \"externally\", using a\nmessage call and not directly via jumps.\nPlease note that function calls on ``this`` cannot be used in the constructor,\nas the actual contract has not been created yet.\n\nFunctions of other contracts have to be called externally. For an external call,\nall function arguments have to be copied to memory.\n\n.. note::\n A function call from one contract to another does not create its own transaction,\n it is a message call as part of the overall transaction.\n\nWhen calling functions of other contracts, you can specify the amount of Wei or\ngas sent with the call with the special options ``{value: 10, gas: 10000}``.\nNote that it is discouraged to specify gas values explicitly, since the gas costs\nof opcodes can change in the future. Any Wei you send to the contract is added\nto the total balance of that contract:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.2 <0.9.0;\n\n contract InfoFeed {\n function info() public payable returns (uint ret) { return 42; }\n }\n\n contract Consumer {\n InfoFeed feed;\n function setFeed(InfoFeed addr) public { feed = addr; }\n function callFeed() public { feed.info{value: 10, gas: 800}(); }\n }\n\nYou need to use the modifier ``payable`` with the ``info`` function because\notherwise, the ``value`` option would not be available.\n\n.. warning::\n Be careful that ``feed.info{value: 10, gas: 800}`` only locally sets the\n ``value`` and amount of ``gas`` sent with the function call, and the\n parentheses at the end perform the actual call. So\n ``feed.info{value: 10, gas: 800}`` does not call the function and\n the ``value`` and ``gas`` settings are lost, only\n ``feed.info{value: 10, gas: 800}()`` performs the function call.\n\n.. warning::\n Due to the fact that the EVM considers a call to a non-existing contract to\n always succeed, Solidity uses the ``extcodesize`` opcode to check that\n the contract that is about to be called actually exists (it contains code)\n and causes an exception if it does not. This check is skipped if the return\n data will be decoded after the call and thus the ABI decoder will catch the\n case of a non-existing contract.\n\n This check is not performed in case of :ref:`low-level calls ` which\n operate on addresses rather than contract instances.\n\n.. warning::\n Be careful when using high-level calls to\n :ref:`precompiled contracts `,\n since the compiler considers them non-existing according to the\n above logic even though they execute code and can return data.\n\n.. note::\n Since the version 0.8.10, the compiler does not check ``extcodesize`` on\n high-level external calls if return data is expected, because an empty code\n will be unable to return data, and the ABI decoder will revert.\n As a consequence, this allows high-level external calls to precompiled\n contracts, since they can return data despite having no code\n associated with their addresses.\n\n Read about :ref:`precompiled contracts ` and\n :ref:`low-level calls `\n for more information.\n\nFunction calls also cause exceptions if the called contract itself\nthrows an exception or goes out of gas.\n\n.. warning::\n Any interaction with another contract imposes a potential danger, especially\n if the source code of the contract is not known in advance. The\n current contract hands over control to the called contract and that may potentially\n do just about anything. Even if the called contract inherits from a known parent contract,\n the inheriting contract is only required to have a correct interface. The\n implementation of the contract, however, can be completely arbitrary and thus,\n pose a danger. In addition, be prepared in case it calls into other contracts of\n your system or even back into the calling contract before the first\n call returns. This means\n that the called contract can change state variables of the calling contract\n via its functions. Write your functions in a way that, for example, calls to\n external functions happen after any changes to state variables in your contract\n so your contract is not vulnerable to a reentrancy exploit.\n\n.. note::\n Before Solidity 0.6.2, the recommended way to specify the value and gas was to\n use ``f.value(x).gas(g)()``. This was deprecated in Solidity 0.6.2 and is no\n longer possible since Solidity 0.7.0.\n\nFunction Calls with Named Parameters\n------------------------------------\n\nFunction call arguments can be given by name, in any order,\nif they are enclosed in ``{ }`` as can be seen in the following\nexample. The argument list has to coincide by name with the list of\nparameters from the function declaration, but can be in arbitrary order.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.0 <0.9.0;\n\n contract C {\n mapping(uint => uint) data;\n\n function f() public {\n set({value: 2, key: 3});\n }\n\n function set(uint key, uint value) public {\n data[key] = value;\n }\n }\n\nOmitted Names in Function Definitions\n-------------------------------------\n\nThe names of parameters and return values in the function declaration can be omitted.\nThose items with omitted names will still be present on the stack, but they are\ninaccessible by name. An omitted return value name\ncan still return a value to the caller by use of the ``return`` statement.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.22 <0.9.0;\n\n contract C {\n // omitted name for parameter\n function func(uint k, uint) public pure returns(uint) {\n return k;\n }\n }\n\n\n.. index:: ! new, contracts;creating\n\n.. _creating-contracts:\n\nCreating Contracts via ``new``\n==============================\n\nA contract can create other contracts using the ``new`` keyword. The full\ncode of the contract being created has to be known when the creating contract\nis compiled so recursive creation-dependencies are not possible.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n contract D {\n uint public x;\n constructor(uint a) payable {\n x = a;\n }\n }\n\n contract C {\n D d = new D(4); // will be executed as part of C's constructor\n\n function createD(uint arg) public {\n D newD = new D(arg);\n newD.x();\n }\n\n function createAndEndowD(uint arg, uint amount) public payable {\n // Send ether along with the creation\n D newD = new D{value: amount}(arg);\n newD.x();\n }\n }\n\nAs seen in the example, it is possible to send Ether while creating\nan instance of ``D`` using the ``value`` option, but it is not possible\nto limit the amount of gas.\nIf the creation fails (due to out-of-stack, not enough balance or other problems),\nan exception is thrown.\n\n.. _salted-contract-creations:\n\nSalted contract creations / create2\n-----------------------------------\n\nWhen creating a contract, the address of the contract is computed from\nthe address of the creating contract and a counter that is increased with\neach contract creation.\n\nIf you specify the option ``salt`` (a bytes32 value), then contract creation will\nuse a different mechanism to come up with the address of the new contract:\n\nIt will compute the address from the address of the creating contract,\nthe given salt value, the (creation) bytecode of the created contract and the constructor\narguments.\n\nIn particular, the counter (\"nonce\") is not used. This allows for more flexibility\nin creating contracts: You are able to derive the address of the\nnew contract before it is created. Furthermore, you can rely on this address\nalso in case the creating\ncontracts creates other contracts in the meantime.\n\nThe main use-case here is contracts that act as judges for off-chain interactions,\nwhich only need to be created if there is a dispute.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n contract D {\n uint public x;\n constructor(uint a) {\n x = a;\n }\n }\n\n contract C {\n function createDSalted(bytes32 salt, uint arg) public {\n // This complicated expression just tells you how the address\n // can be pre-computed. It is just there for illustration.\n // You actually only need ``new D{salt: salt}(arg)``.\n address predictedAddress = address(uint160(uint(keccak256(abi.encodePacked(\n bytes1(0xff),\n address(this),\n salt,\n keccak256(abi.encodePacked(\n type(D).creationCode,\n abi.encode(arg)\n ))\n )))));\n\n D d = new D{salt: salt}(arg);\n require(address(d) == predictedAddress);\n }\n }\n\n.. warning::\n There are some peculiarities in relation to salted creation. A contract can be\n re-created at the same address after having been destroyed. Yet, it is possible\n for that newly created contract to have a different deployed bytecode even\n though the creation bytecode has been the same (which is a requirement because\n otherwise the address would change). This is due to the fact that the constructor\n can query external state that might have changed between the two creations\n and incorporate that into the deployed bytecode before it is stored.\n\n\nOrder of Evaluation of Expressions\n==================================\n\nThe evaluation order of expressions is not specified (more formally, the order\nin which the children of one node in the expression tree are evaluated is not\nspecified, but they are of course evaluated before the node itself). It is only\nguaranteed that statements are executed in order and short-circuiting for\nboolean expressions is done.\n\n.. index:: ! assignment\n\nAssignment\n==========\n\n.. index:: ! assignment;destructuring\n\nDestructuring Assignments and Returning Multiple Values\n-------------------------------------------------------\n\nSolidity internally allows tuple types, i.e. a list of objects\nof potentially different types whose number is a constant at\ncompile-time. Those tuples can be used to return multiple values at the same time.\nThese can then either be assigned to newly declared variables\nor to pre-existing variables (or LValues in general).\n\nTuples are not proper types in Solidity, they can only be used to form syntactic\ngroupings of expressions.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n\n contract C {\n uint index;\n\n function f() public pure returns (uint, bool, uint) {\n return (7, true, 2);\n }\n\n function g() public {\n // Variables declared with type and assigned from the returned tuple,\n // not all elements have to be specified (but the number must match).\n (uint x, , uint y) = f();\n // Common trick to swap values -- does not work for non-value storage types.\n (x, y) = (y, x);\n // Components can be left out (also for variable declarations).\n (index, , ) = f(); // Sets the index to 7\n }\n }\n\nIt is not possible to mix variable declarations and non-declaration assignments,\ni.e. the following is not valid: ``(x, uint y) = (1, 2);``\n\n.. note::\n Prior to version 0.5.0 it was possible to assign to tuples of smaller size, either\n filling up on the left or on the right side (which ever was empty). This is\n now disallowed, so both sides have to have the same number of components.\n\n.. warning::\n Be careful when assigning to multiple variables at the same time when\n reference types are involved, because it could lead to unexpected\n copying behavior.\n\nComplications for Arrays and Structs\n------------------------------------\n\nThe semantics of assignments are more complicated for non-value types like arrays and structs,\nincluding ``bytes`` and ``string``, see :ref:`Data location and assignment behavior ` for details.\n\nIn the example below the call to ``g(x)`` has no effect on ``x`` because it creates\nan independent copy of the storage value in memory. However, ``h(x)`` successfully modifies ``x``\nbecause only a reference and not a copy is passed.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.22 <0.9.0;\n\n contract C {\n uint[20] x;\n\n function f() public {\n g(x);\n h(x);\n }\n\n function g(uint[20] memory y) internal pure {\n y[2] = 3;\n }\n\n function h(uint[20] storage y) internal {\n y[3] = 4;\n }\n }\n\n.. index:: ! scoping, declarations, default value\n\n.. _default-value:\n\nScoping and Declarations\n========================\n\nA variable which is declared will have an initial default\nvalue whose byte-representation is all zeros.\nThe \"default values\" of variables are the typical \"zero-state\"\nof whatever the type is. For example, the default value for a ``bool``\nis ``false``. The default value for the ``uint`` or ``int``\ntypes is ``0``. For statically-sized arrays and ``bytes1`` to\n``bytes32``, each individual\nelement will be initialized to the default value corresponding\nto its type. For dynamically-sized arrays, ``bytes``\nand ``string``, the default value is an empty array or string.\nFor the ``enum`` type, the default value is its first member.\n\nScoping in Solidity follows the widespread scoping rules of C99\n(and many other languages): Variables are visible from the point right after their declaration\nuntil the end of the smallest ``{ }``-block that contains the declaration.\nAs an exception to this rule, variables declared in the\ninitialization part of a for-loop are only visible until the end of the for-loop.\n\nVariables that are parameter-like (function parameters, modifier parameters,\ncatch parameters, ...) are visible inside the code block that follows -\nthe body of the function/modifier for a function and modifier parameter and the catch block\nfor a catch parameter.\n\nVariables and other items declared outside of a code block, for example functions, contracts,\nuser-defined types, etc., are visible even before they were declared. This means you can\nuse state variables before they are declared and call functions recursively.\n\nAs a consequence, the following examples will compile without warnings, since\nthe two variables have the same name but disjoint scopes.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n contract C {\n function minimalScoping() pure public {\n {\n uint same;\n same = 1;\n }\n\n {\n uint same;\n same = 3;\n }\n }\n }\n\nAs a special example of the C99 scoping rules, note that in the following,\nthe first assignment to ``x`` will actually assign the outer and not the inner variable.\nIn any case, you will get a warning about the outer variable being shadowed.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n // This will report a warning\n contract C {\n function f() pure public returns (uint) {\n uint x = 1;\n {\n x = 2; // this will assign to the outer variable\n uint x;\n }\n return x; // x has value 2\n }\n }\n\n.. warning::\n Before version 0.5.0 Solidity followed the same scoping rules as\n JavaScript, that is, a variable declared anywhere within a function would be in scope\n for the entire function, regardless where it was declared. The following example shows a code snippet that used\n to compile but leads to an error starting from version 0.5.0.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n // This will not compile\n contract C {\n function f() pure public returns (uint) {\n x = 2;\n uint x;\n return x;\n }\n }\n\n\n.. index:: ! safe math, safemath, checked, unchecked\n.. _unchecked:\n\nChecked or Unchecked Arithmetic\n===============================\n\nAn overflow or underflow is the situation where the resulting value of an arithmetic operation,\nwhen executed on an unrestricted integer, falls outside the range of the result type.\n\nPrior to Solidity 0.8.0, arithmetic operations would always wrap in case of\nunder- or overflow leading to widespread use of libraries that introduce\nadditional checks.\n\nSince Solidity 0.8.0, all arithmetic operations revert on over- and underflow by default,\nthus making the use of these libraries unnecessary.\n\nTo obtain the previous behavior, an ``unchecked`` block can be used:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.0;\n contract C {\n function f(uint a, uint b) pure public returns (uint) {\n // This subtraction will wrap on underflow.\n unchecked { return a - b; }\n }\n function g(uint a, uint b) pure public returns (uint) {\n // This subtraction will revert on underflow.\n return a - b;\n }\n }\n\nThe call to ``f(2, 3)`` will return ``2**256-1``, while ``g(2, 3)`` will cause\na failing assertion.\n\nThe ``unchecked`` block can be used everywhere inside a block, but not as a replacement\nfor a block. It also cannot be nested.\n\nThe setting only affects the statements that are syntactically inside the block.\nFunctions called from within an ``unchecked`` block do not inherit the property.\n\n.. note::\n To avoid ambiguity, you cannot use ``_;`` inside an ``unchecked`` block.\n\nThe following operators will cause a failing assertion on overflow or underflow\nand will wrap without an error if used inside an unchecked block:\n\n``++``, ``--``, ``+``, binary ``-``, unary ``-``, ``*``, ``/``, ``%``, ``**``\n\n``+=``, ``-=``, ``*=``, ``/=``, ``%=``\n\n.. warning::\n It is not possible to disable the check for division by zero\n or modulo by zero using the ``unchecked`` block.\n\n.. note::\n Bitwise operators do not perform overflow or underflow checks.\n This is particularly visible when using bitwise shifts (``<<``, ``>>``, ``<<=``, ``>>=``) in\n place of integer division and multiplication by a power of 2.\n For example ``type(uint256).max << 3`` does not revert even though ``type(uint256).max * 8`` would.\n\n.. note::\n The second statement in ``int x = type(int).min; -x;`` will result in an overflow\n because the negative range can hold one more value than the positive range.\n\nExplicit type conversions will always truncate and never cause a failing assertion\nwith the exception of a conversion from an integer to an enum type.\n\n.. index:: ! exception, ! throw, ! assert, ! require, ! revert, ! errors\n\n.. _assert-and-require:\n\nError handling: Assert, Require, Revert and Exceptions\n======================================================\n\nSolidity uses state-reverting exceptions to handle errors.\nSuch an exception undoes all changes made to the\nstate in the current call (and all its sub-calls) and\nflags an error to the caller.\n\nWhen exceptions happen in a sub-call, they \"bubble up\" (i.e.,\nexceptions are rethrown) automatically unless they are caught in\na ``try/catch`` statement. Exceptions to this rule are ``send``\nand the low-level functions ``call``, ``delegatecall`` and\n``staticcall``: they return ``false`` as their first return value in case\nof an exception instead of \"bubbling up\".\n\n.. warning::\n The low-level functions ``call``, ``delegatecall`` and\n ``staticcall`` return ``true`` as their first return value\n if the account called is non-existent, as part of the design\n of the EVM. Account existence must be checked prior to calling if needed.\n\nExceptions can contain error data that is passed back to the caller\nin the form of :ref:`error instances `.\nThe built-in errors ``Error(string)`` and ``Panic(uint256)`` are\nused by special functions, as explained below. ``Error`` is used for \"regular\" error conditions\nwhile ``Panic`` is used for errors that should not be present in bug-free code.\n\n.. _assert-and-require-statements:\n\nPanic via ``assert`` and Error via ``require``\n----------------------------------------------\n\nThe convenience functions ``assert`` and ``require`` can be used to check for conditions and throw an exception\nif the condition is not met.\n\nThe ``assert`` function creates an error of type ``Panic(uint256)``.\nThe same error is created by the compiler in certain situations as listed below.\n\nAssert should only be used to test for internal\nerrors, and to check invariants. Properly functioning code should\nnever create a Panic, not even on invalid external input.\nIf this happens, then there\nis a bug in your contract which you should fix. Language analysis\ntools can evaluate your contract to identify the conditions and\nfunction calls which will cause a Panic.\n\nA Panic exception is generated in the following situations.\nThe error code supplied with the error data indicates the kind of panic.\n\n#. 0x00: Used for generic compiler inserted panics.\n#. 0x01: If you call ``assert`` with an argument that evaluates to false.\n#. 0x11: If an arithmetic operation results in underflow or overflow outside of an ``unchecked { ... }`` block.\n#. 0x12; If you divide or modulo by zero (e.g. ``5 / 0`` or ``23 % 0``).\n#. 0x21: If you convert a value that is too big or negative into an enum type.\n#. 0x22: If you access a storage byte array that is incorrectly encoded.\n#. 0x31: If you call ``.pop()`` on an empty array.\n#. 0x32: If you access an array, ``bytesN`` or an array slice at an out-of-bounds or negative index (i.e. ``x[i]`` where ``i >= x.length`` or ``i < 0``).\n#. 0x41: If you allocate too much memory or create an array that is too large.\n#. 0x51: If you call a zero-initialized variable of internal function type.\n\nThe ``require`` function provides three overloads:\n\n1. ``require(bool)`` which will revert without any data (not even an error selector).\n2. ``require(bool, string)`` which will revert with an ``Error(string)``.\n3. ``require(bool, error)`` which will revert with the custom, user supplied error provided as the second argument.\n\n.. note::\n ``require`` arguments are evaluated unconditionally, so take special care to make sure that\n they are not expressions with unexpected side-effects.\n For example, in ``require(condition, CustomError(f()));`` and ``require(condition, f());``,\n function ``f()`` will be called regardless of whether the supplied condition is ``true`` or ``false``.\n\nAn ``Error(string)`` exception (or an exception without data) is generated\nby the compiler in the following situations:\n\n#. Calling ``require(x)`` where ``x`` evaluates to ``false``.\n#. If you use ``revert()`` or ``revert(\"description\")``.\n#. If you perform an external function call targeting a contract that contains no code.\n#. If your contract receives Ether via a public function without\n ``payable`` modifier (including the constructor and the fallback function).\n#. If your contract receives Ether via a public getter function.\n\nFor the following cases, the error data from the external call\n(if provided) is forwarded. This means that it can either cause\nan ``Error`` or a ``Panic`` (or whatever else was given):\n\n#. If a ``.transfer()`` fails.\n#. If you call a function via a message call but it does not finish\n properly (i.e., it runs out of gas, has no matching function, or\n throws an exception itself), except when a low level operation\n ``call``, ``send``, ``delegatecall``, ``callcode`` or ``staticcall``\n is used. The low level operations never throw exceptions but\n indicate failures by returning ``false``.\n#. If you create a contract using the ``new`` keyword but the contract\n creation :ref:`does not finish properly`.\n\nYou can optionally provide a message string or a custom error to ``require``, but not to ``assert``.\n\n.. note::\n If you do not provide a string or custom error argument to ``require``, it will revert\n with empty error data, not even including the error selector.\n\n\nThe following example shows how you can use ``require`` to check conditions on inputs\nand ``assert`` for internal error checking.\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.2 <0.9.0;\n\n contract Sharer {\n function sendHalf(address payable addr) public payable returns (uint balance) {\n require(msg.value % 2 == 0, \"Even value required.\");\n uint balanceBeforeTransfer = address(this).balance;\n (bool success, ) = addr.call{value: msg.value / 2}(\"\");\n require(success);\n // Since require will stop execution and revert if success is false,\n // there should be no way for us to still have half of the Ether.\n assert(address(this).balance == balanceBeforeTransfer - msg.value / 2);\n return address(this).balance;\n }\n }\n\nInternally, Solidity performs a revert operation (instruction\n``0xfd``). This causes\nthe EVM to revert all changes made to the state. The reason for reverting\nis that there is no safe way to continue execution, because an expected effect\ndid not occur. Because we want to keep the atomicity of transactions, the\nsafest action is to revert all changes and make the whole transaction\n(or at least call) without effect.\n\nIn both cases, the caller can react on such failures using ``try``/``catch``, but\nthe changes in the callee will always be reverted.\n\n.. note::\n\n Panic exceptions used to use the ``invalid`` opcode before Solidity 0.8.0,\n which consumed all gas available to the call.\n Exceptions that use ``require`` used to consume all gas until before the Metropolis release.\n\n.. _revert-statement:\n\n``revert``\n----------\n\nA direct revert can be triggered using the ``revert`` statement and the ``revert`` function.\n\nThe ``revert`` statement takes a custom error as direct argument without parentheses:\n\n revert CustomError(arg1, arg2);\n\nFor backward-compatibility reasons, there is also the ``revert()`` function, which uses parentheses\nand accepts a string:\n\n revert();\n revert(\"description\");\n\nThe error data will be passed back to the caller and can be caught there.\nUsing ``revert()`` causes a revert without any error data while ``revert(\"description\")``\nwill create an ``Error(string)`` error.\n\nUsing a custom error instance will usually be much cheaper than a string description,\nbecause you can use the name of the error to describe it, which is encoded in only\nfour bytes. A longer description can be supplied via NatSpec which does not incur\nany costs.\n\nThe following example shows how to use an error string and a custom error instance\ntogether with ``revert`` and the equivalent ``require``:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n\n contract VendingMachine {\n address owner;\n error Unauthorized();\n function buy(uint amount) public payable {\n if (amount > msg.value / 2 ether)\n revert(\"Not enough Ether provided.\");\n // Alternative way to do it:\n require(\n amount <= msg.value / 2 ether,\n \"Not enough Ether provided.\"\n );\n // Perform the purchase.\n }\n function withdraw() public {\n if (msg.sender != owner)\n revert Unauthorized();\n\n (bool success, ) = payable(msg.sender).call{value: address(this).balance}(\"\");\n require(success);\n }\n }\n\nThe two ways ``if (!condition) revert(...);`` and ``require(condition, ...);`` are\nequivalent as long as the arguments to ``revert`` and ``require`` do not have side-effects,\nfor example if they are just strings.\n\n.. note::\n The ``require`` function is evaluated just as any other function.\n This means that all arguments are evaluated before the function itself is executed.\n In particular, in ``require(condition, f())`` the function ``f`` is executed even if\n ``condition`` is true.\n\nThe provided string is :ref:`abi-encoded ` as if it were a call to a function ``Error(string)``.\nIn the above example, ``revert(\"Not enough Ether provided.\");`` returns the following hexadecimal as error return data:\n\n.. code::\n\n 0x08c379a0 // Function selector for Error(string)\n 0x0000000000000000000000000000000000000000000000000000000000000020 // Data offset\n 0x000000000000000000000000000000000000000000000000000000000000001a // String length\n 0x4e6f7420656e6f7567682045746865722070726f76696465642e000000000000 // String data\n\nThe provided message can be retrieved by the caller using ``try``/``catch`` as shown below.\n\n.. note::\n There used to be a keyword called ``throw`` with the same semantics as ``revert()`` which\n was deprecated in version 0.4.13 and removed in version 0.5.0.\n\n\n.. _try-catch:\n\n``try``/``catch``\n-----------------\n\nA failure in an external call can be caught using a try/catch statement, as follows:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.1;\n\n interface DataFeed { function getData(address token) external returns (uint value); }\n\n contract FeedConsumer {\n DataFeed feed;\n uint errorCount;\n function rate(address token) public returns (uint value, bool success) {\n // Permanently disable the mechanism if there are\n // more than 10 errors.\n require(errorCount < 10);\n try feed.getData(token) returns (uint v) {\n return (v, true);\n } catch Error(string memory /*reason*/) {\n // This is executed in case\n // revert was called inside getData\n // and a reason string was provided.\n errorCount++;\n return (0, false);\n } catch Panic(uint /*errorCode*/) {\n // This is executed in case of a panic,\n // i.e. a serious error like division by zero\n // or overflow. The error code can be used\n // to determine the kind of error.\n errorCount++;\n return (0, false);\n } catch (bytes memory /*lowLevelData*/) {\n // This is executed in case revert() was used.\n errorCount++;\n return (0, false);\n }\n }\n }\n\nThe ``try`` keyword has to be followed by an expression representing an external function call\nor a contract creation (``new ContractName()``).\nErrors inside the expression are not caught (for example if it is a complex expression\nthat also involves internal function calls), only a revert happening inside the external\ncall itself. The ``returns`` part (which is optional) that follows declares return variables\nmatching the types returned by the external call. In case there was no error,\nthese variables are assigned and the contract's execution continues inside the\nfirst success block. If the end of the success block is reached, execution continues after the ``catch`` blocks.\n\nSolidity supports different kinds of catch blocks depending on the\ntype of error:\n\n- ``catch Error(string memory reason) { ... }``: This catch clause is executed if the error was caused by ``revert(\"reasonString\")`` or\n ``require(false, \"reasonString\")`` (or an internal error that causes such an\n exception).\n\n- ``catch Panic(uint errorCode) { ... }``: If the error was caused by a panic, i.e. by a failing ``assert``, division by zero,\n invalid array access, arithmetic overflow and others, this catch clause will be run.\n\n- ``catch (bytes memory lowLevelData) { ... }``: This clause is executed if the error signature\n does not match any other clause, if there was an error while decoding the error\n message, or\n if no error data was provided with the exception.\n The declared variable provides access to the low-level error data in that case.\n\n- ``catch { ... }``: If you are not interested in the error data, you can just use\n ``catch { ... }`` (even as the only catch clause) instead of the previous clause.\n\n\nIt is planned to support other types of error data in the future.\nThe strings ``Error`` and ``Panic`` are currently parsed as is and are not treated as identifiers.\n\nIn order to catch all error cases, you have to have at least the clause\n``catch { ...}`` or the clause ``catch (bytes memory lowLevelData) { ... }``.\n\nThe variables declared in the ``returns`` and the ``catch`` clause are only\nin scope in the block that follows.\n\n.. note::\n\n If an error happens during the decoding of the return data\n inside a try/catch-statement, this causes an exception in the currently\n executing contract and because of that, it is not caught in the catch clause.\n If there is an error during decoding of ``catch Error(string memory reason)``\n and there is a low-level catch clause, this error is caught there.\n\n.. note::\n\n If execution reaches a catch-block, then the state-changing effects of\n the external call have been reverted. If execution reaches\n the success block, the effects were not reverted.\n If the effects have been reverted, then execution either continues\n in a catch block or the execution of the try/catch statement itself\n reverts (for example due to decoding failures as noted above or\n due to not providing a low-level catch clause).\n\n.. note::\n The reason behind a failed call can be manifold. Do not assume that\n the error message is coming directly from the called contract:\n The error might have happened deeper down in the call chain and the\n called contract just forwarded it. Also, it could be due to an\n out-of-gas situation and not a deliberate error condition:\n The caller always retains at least 1/64th of the gas in a call and thus\n even if the called contract goes out of gas, the caller still\n has some gas left.\n" }, { "path": "docs/credits-and-attribution.rst", "content": ".. This page is meant to be linked to from the footer.\n\n:orphan:\n\n#######################\nCredits and Attribution\n#######################\n\nWebsite icons\n=============\n\n.. |icon-share-solid| image:: _static/img/solid-share-arrow.svg\n.. _share icon: https://fontawesome.com/v5.15/icons/share?style=solid\n.. _Font Awesome Free License: https://fontawesome.com/license/free\n\n+-------------------------+-----------------------------------------------------------------------+\n| Icon | Attribution |\n+=========================+=======================================================================+\n| |icon-share-solid| | - Source: `share icon`_ from Font Awesome 5.15.0. |\n| | - License: `Font Awesome Free License`_ (CC BY 4.0). |\n+-------------------------+-----------------------------------------------------------------------+\n" }, { "path": "docs/docs.sh", "content": "#!/usr/bin/env bash\n\n#------------------------------------------------------------------------------\n# Bash script to build the Solidity Sphinx documentation locally.\n#\n# The documentation for solidity is hosted at:\n#\n# https://docs.soliditylang.org\n#\n# ------------------------------------------------------------------------------\n# This file is part of solidity.\n#\n# solidity is free software: you can redistribute it and/or modify\n# it under the terms of the GNU General Public License as published by\n# the Free Software Foundation, either version 3 of the License, or\n# (at your option) any later version.\n#\n# solidity is distributed in the hope that it will be useful,\n# but WITHOUT ANY WARRANTY; without even the implied warranty of\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n# GNU General Public License for more details.\n#\n# You should have received a copy of the GNU General Public License\n# along with solidity. If not, see \n#\n# (c) 2016 solidity contributors.\n#------------------------------------------------------------------------------\n\nset -euo pipefail\n\nscript_dir=\"$(dirname \"$0\")\"\n\ncd \"${script_dir}\"\n# TODO `--ignore-installed` now fixes an issue where pip tries to uninstall a Debian installed package, but is unable to\n# TODO since Debian has decided to not use the RECORD file, which then breaks pip.\n# TODO https://github.com/pypa/pip/issues/11631 and https://bugs.launchpad.net/ubuntu/+source/wheel/+bug/2063151\npip3 install -r requirements.txt --ignore-installed --upgrade --upgrade-strategy eager\nsphinx-build -nW -b html -d _build/doctrees . _build/html\n" }, { "path": "docs/examples/blind-auction.rst", "content": ".. index:: auction;blind, auction;open, blind auction, open auction\n\n*************\nBlind Auction\n*************\n\nIn this section, we will show how easy it is to create a completely blind\nauction contract on Ethereum. We will start with an open auction where\neveryone can see the bids that are made and then extend this contract into a\nblind auction where it is not possible to see the actual bid until the bidding\nperiod ends.\n\n.. _simple_auction:\n\nSimple Open Auction\n===================\n\nThe general idea of the following simple auction contract is that everyone can\nsend their bids during a bidding period. The bids already include sending some compensation,\ne.g. Ether, in order to bind the bidders to their bid. If the highest bid is\nraised, the previous highest bidder gets their Ether back. After the end of\nthe bidding period, the contract has to be called manually for the beneficiary\nto receive their Ether - contracts cannot activate themselves.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n contract SimpleAuction {\n // Parameters of the auction. Times are either\n // absolute unix timestamps (seconds since 1970-01-01)\n // or time periods in seconds.\n address payable public beneficiary;\n uint public auctionEndTime;\n\n // Current state of the auction.\n address public highestBidder;\n uint public highestBid;\n\n // Allowed withdrawals of previous bids\n mapping(address => uint) pendingReturns;\n\n // Set to true at the end, disallows any change.\n // By default initialized to `false`.\n bool ended;\n\n // Events that will be emitted on changes.\n event HighestBidIncreased(address bidder, uint amount);\n event AuctionEnded(address winner, uint amount);\n\n // Errors that describe failures.\n\n // The triple-slash comments are so-called natspec\n // comments. They will be shown when the user\n // is asked to confirm a transaction or\n // when an error is displayed.\n\n /// The auction has already ended.\n error AuctionAlreadyEnded();\n /// There is already a higher or equal bid.\n error BidNotHighEnough(uint highestBid);\n /// The auction has not ended yet.\n error AuctionNotYetEnded();\n /// The function auctionEnd has already been called.\n error AuctionEndAlreadyCalled();\n\n /// Create a simple auction with `biddingTime`\n /// seconds bidding time on behalf of the\n /// beneficiary address `beneficiaryAddress`.\n constructor(\n uint biddingTime,\n address payable beneficiaryAddress\n ) {\n beneficiary = beneficiaryAddress;\n auctionEndTime = block.timestamp + biddingTime;\n }\n\n /// Bid on the auction with the value sent\n /// together with this transaction.\n /// The value will only be refunded if the\n /// auction is not won.\n function bid() external payable {\n // No arguments are necessary, all\n // information is already part of\n // the transaction. The keyword payable\n // is required for the function to\n // be able to receive Ether.\n\n // Revert the call if the bidding\n // period is over.\n if (block.timestamp > auctionEndTime)\n revert AuctionAlreadyEnded();\n\n // If the bid is not higher, send the\n // Ether back (the revert statement\n // will revert all changes in this\n // function execution including\n // it having received the Ether).\n if (msg.value <= highestBid)\n revert BidNotHighEnough(highestBid);\n\n if (highestBid != 0) {\n // Sending back the Ether by simply using\n // highestBidder.send(highestBid) is a security risk\n // because it could execute an untrusted contract.\n // It is always safer to let the recipients\n // withdraw their Ether themselves.\n pendingReturns[highestBidder] += highestBid;\n }\n highestBidder = msg.sender;\n highestBid = msg.value;\n emit HighestBidIncreased(msg.sender, msg.value);\n }\n\n /// Withdraw a bid that was overbid.\n function withdraw() external returns (bool) {\n uint amount = pendingReturns[msg.sender];\n if (amount > 0) {\n // It is important to set this to zero because the recipient\n // can call this function again as part of the receiving call\n // before `call` returns.\n pendingReturns[msg.sender] = 0;\n\n // msg.sender is not of type `address payable` and must be\n // explicitly converted using `payable(msg.sender)` in order\n // use the member function `call()`.\n (bool success, ) = payable(msg.sender).call{value: amount}(\"\");\n if (!success) {\n // No need to call throw here, just reset the amount owing\n pendingReturns[msg.sender] = amount;\n return false;\n }\n }\n return true;\n }\n\n /// End the auction and send the highest bid\n /// to the beneficiary.\n function auctionEnd() external {\n // It is a good guideline to structure functions that interact\n // with other contracts (i.e. they call functions or send Ether)\n // into three phases:\n // 1. checking conditions\n // 2. performing actions (potentially changing conditions)\n // 3. interacting with other contracts\n // If these phases are mixed up, the other contract could call\n // back into the current contract and modify the state or cause\n // effects (ether payout) to be performed multiple times.\n // If functions called internally include interaction with external\n // contracts, they also have to be considered interaction with\n // external contracts.\n\n // 1. Conditions\n if (block.timestamp < auctionEndTime)\n revert AuctionNotYetEnded();\n if (ended)\n revert AuctionEndAlreadyCalled();\n\n // 2. Effects\n ended = true;\n emit AuctionEnded(highestBidder, highestBid);\n\n // 3. Interaction\n (bool success, ) = beneficiary.call{value: highestBid}(\"\");\n require(success);\n }\n }\n\nBlind Auction\n=============\n\nThe previous open auction is extended to a blind auction in the following. The\nadvantage of a blind auction is that there is no time pressure towards the end\nof the bidding period. Creating a blind auction on a transparent computing\nplatform might sound like a contradiction, but cryptography comes to the\nrescue.\n\nDuring the **bidding period**, a bidder does not actually send their bid, but\nonly a hashed version of it. Since it is currently considered practically\nimpossible to find two (sufficiently long) values whose hash values are equal,\nthe bidder commits to the bid by that. After the end of the bidding period,\nthe bidders have to reveal their bids: They send their values unencrypted, and\nthe contract checks that the hash value is the same as the one provided during\nthe bidding period.\n\nAnother challenge is how to make the auction **binding and blind** at the same\ntime: The only way to prevent the bidder from just not sending the Ether after\nthey won the auction is to make them send it together with the bid. Since value\ntransfers cannot be blinded in Ethereum, anyone can see the value.\n\nThe following contract solves this problem by accepting any value that is\nlarger than the highest bid. Since this can of course only be checked during\nthe reveal phase, some bids might be **invalid**, and this is on purpose (it\neven provides an explicit flag to place invalid bids with high-value\ntransfers): Bidders can confuse competition by placing several high or low\ninvalid bids.\n\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n contract BlindAuction {\n struct Bid {\n bytes32 blindedBid;\n uint deposit;\n }\n\n address payable public beneficiary;\n uint public biddingEnd;\n uint public revealEnd;\n bool public ended;\n\n mapping(address => Bid[]) public bids;\n\n address public highestBidder;\n uint public highestBid;\n\n // Allowed withdrawals of previous bids\n mapping(address => uint) pendingReturns;\n\n event AuctionEnded(address winner, uint highestBid);\n\n // Errors that describe failures.\n\n /// The function has been called too early.\n /// Try again at `time`.\n error TooEarly(uint time);\n /// The function has been called too late.\n /// It cannot be called after `time`.\n error TooLate(uint time);\n /// The function auctionEnd has already been called.\n error AuctionEndAlreadyCalled();\n\n // Modifiers are a convenient way to validate inputs to\n // functions. `onlyBefore` is applied to `bid` below:\n // The new function body is the modifier's body where\n // `_` is replaced by the old function body.\n modifier onlyBefore(uint time) {\n if (block.timestamp >= time) revert TooLate(time);\n _;\n }\n modifier onlyAfter(uint time) {\n if (block.timestamp <= time) revert TooEarly(time);\n _;\n }\n\n constructor(\n uint biddingTime,\n uint revealTime,\n address payable beneficiaryAddress\n ) {\n beneficiary = beneficiaryAddress;\n biddingEnd = block.timestamp + biddingTime;\n revealEnd = biddingEnd + revealTime;\n }\n\n /// Place a blinded bid with `blindedBid` =\n /// keccak256(abi.encodePacked(value, fake, secret)).\n /// The sent ether is only refunded if the bid is correctly\n /// revealed in the revealing phase. The bid is valid if the\n /// ether sent together with the bid is at least \"value\" and\n /// \"fake\" is not true. Setting \"fake\" to true and sending\n /// not the exact amount are ways to hide the real bid but\n /// still make the required deposit. The same address can\n /// place multiple bids.\n function bid(bytes32 blindedBid)\n external\n payable\n onlyBefore(biddingEnd)\n {\n bids[msg.sender].push(Bid({\n blindedBid: blindedBid,\n deposit: msg.value\n }));\n }\n\n /// Reveal your blinded bids. You will get a refund for all\n /// correctly blinded invalid bids and for all bids except for\n /// the totally highest.\n function reveal(\n uint[] calldata values,\n bool[] calldata fakes,\n bytes32[] calldata secrets\n )\n external\n onlyAfter(biddingEnd)\n onlyBefore(revealEnd)\n {\n uint length = bids[msg.sender].length;\n require(values.length == length);\n require(fakes.length == length);\n require(secrets.length == length);\n\n uint refund;\n for (uint i = 0; i < length; i++) {\n Bid storage bidToCheck = bids[msg.sender][i];\n (uint value, bool fake, bytes32 secret) =\n (values[i], fakes[i], secrets[i]);\n if (bidToCheck.blindedBid != keccak256(abi.encodePacked(value, fake, secret))) {\n // Bid was not actually revealed.\n // Do not refund deposit.\n continue;\n }\n refund += bidToCheck.deposit;\n if (!fake && bidToCheck.deposit >= value) {\n if (placeBid(msg.sender, value))\n refund -= value;\n }\n // Make it impossible for the sender to re-claim\n // the same deposit.\n bidToCheck.blindedBid = bytes32(0);\n }\n (bool success, ) = payable(msg.sender).call{value: refund}(\"\");\n require(success);\n }\n\n /// Withdraw a bid that was overbid.\n function withdraw() external {\n uint amount = pendingReturns[msg.sender];\n if (amount > 0) {\n // It is important to set this to zero because the recipient\n // can call this function again as part of the receiving call\n // before `call` returns (see the remark above about\n // conditions -> effects -> interaction).\n pendingReturns[msg.sender] = 0;\n\n (bool success, ) = payable(msg.sender).call{value: amount}(\"\");\n require(success);\n }\n }\n\n /// End the auction and send the highest bid\n /// to the beneficiary.\n function auctionEnd()\n external\n onlyAfter(revealEnd)\n {\n if (ended) revert AuctionEndAlreadyCalled();\n emit AuctionEnded(highestBidder, highestBid);\n ended = true;\n (bool success, ) = beneficiary.call{value: highestBid}(\"\");\n require(success);\n }\n\n // This is an \"internal\" function which means that it\n // can only be called from the contract itself (or from\n // derived contracts).\n function placeBid(address bidder, uint value) internal\n returns (bool success)\n {\n if (value <= highestBid) {\n return false;\n }\n if (highestBidder != address(0)) {\n // Refund the previously highest bidder.\n pendingReturns[highestBidder] += highestBid;\n }\n highestBid = value;\n highestBidder = bidder;\n return true;\n }\n }\n" }, { "path": "docs/examples/micropayment.rst", "content": "********************\nMicropayment Channel\n********************\n\nIn this section, we will learn how to build an example implementation\nof a payment channel. It uses cryptographic signatures to make\nrepeated transfers of Ether between the same parties secure, instantaneous, and\nwithout transaction fees. For the example, we need to understand how to\nsign and verify signatures, and setup the payment channel.\n\nCreating and verifying signatures\n=================================\n\nImagine Alice wants to send some Ether to Bob, i.e.\nAlice is the sender and Bob is the recipient.\n\nAlice only needs to send cryptographically signed messages off-chain\n(e.g. via email) to Bob and it is similar to writing checks.\n\nAlice and Bob use signatures to authorize transactions, which is possible with smart contracts on Ethereum.\nAlice will build a simple smart contract that lets her transmit Ether, but instead of calling a function herself\nto initiate a payment, she will let Bob do that, and therefore pay the transaction fee.\n\nThe contract will work as follows:\n\n 1. Alice deploys the ``ReceiverPays`` contract, attaching enough Ether to cover the payments that will be made.\n 2. Alice authorizes a payment by signing a message with her private key.\n 3. Alice sends the cryptographically signed message to Bob. The message does not need to be kept secret\n (explained later), and the mechanism for sending it does not matter.\n 4. Bob claims his payment by presenting the signed message to the smart contract, it verifies the\n authenticity of the message and then releases the funds.\n\nCreating the signature\n----------------------\n\nAlice does not need to interact with the Ethereum network\nto sign the transaction, the process is completely offline.\nIn this tutorial, we will sign messages in the browser\nusing `web3.js `_ and\n`MetaMask `_, using the method described in `EIP-712 `_,\nas it provides a number of other security benefits.\n\n.. code-block:: javascript\n\n /// Hashing first makes things easier\n var hash = web3.utils.sha3(\"message to sign\");\n web3.eth.personal.sign(hash, web3.eth.defaultAccount, function () { console.log(\"Signed\"); });\n\n.. note::\n The ``web3.eth.personal.sign`` prepends the length of the\n message to the signed data. Since we hash first, the message\n will always be exactly 32 bytes long, and thus this length\n prefix is always the same.\n\nWhat to Sign\n------------\n\nFor a contract that fulfills payments, the signed message must include:\n\n 1. The recipient's address.\n 2. The amount to be transferred.\n 3. Protection against replay attacks.\n\nA replay attack is when a signed message is reused to claim\nauthorization for a second action. To avoid replay attacks\nwe use the same technique as in Ethereum transactions themselves,\na so-called nonce, which is the number of transactions sent by\nan account. The smart contract checks if a nonce is used multiple times.\n\nAnother type of replay attack can occur when the owner\ndeploys a ``ReceiverPays`` smart contract, makes some\npayments, and then destroys the contract. Later, they decide\nto deploy the ``RecipientPays`` smart contract again, but the\nnew contract does not know the nonces used in the previous\ndeployment, so the attacker can use the old messages again.\n\nAlice can protect against this attack by including the\ncontract's address in the message, and only messages containing\nthe contract's address itself will be accepted. You can find\nan example of this in the first two lines of the ``claimPayment()``\nfunction of the full contract at the end of this section.\n\nFurthermore, instead of destroying the contract by calling ``selfdestruct``,\nwhich is currently deprecated, we will disable the contract's functionalities by freezing it,\nresulting in the reversion of any call after it being frozen.\n\nPacking arguments\n-----------------\n\nNow that we have identified what information to include in the signed message,\nwe are ready to put the message together, hash it, and sign it. For simplicity,\nwe concatenate the data. The `ethereumjs-abi `_\nlibrary provides a function called ``soliditySHA3`` that mimics the behavior of\nSolidity's ``keccak256`` function applied to arguments encoded using ``abi.encodePacked``.\nHere is a JavaScript function that creates the proper signature for the ``ReceiverPays`` example:\n\n.. code-block:: javascript\n\n // recipient is the address that should be paid.\n // amount, in wei, specifies how much ether should be sent.\n // nonce can be any unique number to prevent replay attacks\n // contractAddress is used to prevent cross-contract replay attacks\n function signPayment(recipient, amount, nonce, contractAddress, callback) {\n var hash = \"0x\" + abi.soliditySHA3(\n [\"address\", \"uint256\", \"uint256\", \"address\"],\n [recipient, amount, nonce, contractAddress]\n ).toString(\"hex\");\n\n web3.eth.personal.sign(hash, web3.eth.defaultAccount, callback);\n }\n\nRecovering the Message Signer in Solidity\n-----------------------------------------\n\nIn general, ECDSA signatures consist of two parameters,\n``r`` and ``s``. Signatures in Ethereum include a third\nparameter called ``v``, that you can use to verify which\naccount's private key was used to sign the message, and\nthe transaction's sender. Solidity provides a built-in\nfunction :ref:`ecrecover ` that\naccepts a message along with the ``r``, ``s`` and ``v`` parameters\nand returns the address that was used to sign the message.\n\nExtracting the Signature Parameters\n-----------------------------------\n\nSignatures produced by web3.js are the concatenation of ``r``,\n``s`` and ``v``, so the first step is to split these parameters\napart. You can do this on the client-side, but doing it inside\nthe smart contract means you only need to send one signature\nparameter rather than three. Splitting apart a byte array into\nits constituent parts is a mess, so we use\n:doc:`inline assembly ` to do the job in the ``splitSignature``\nfunction (the third function in the full contract at the end of this section).\n\nComputing the Message Hash\n--------------------------\n\nThe smart contract needs to know exactly what parameters were signed, and so it\nmust recreate the message from the parameters and use that for signature verification.\nThe functions ``prefixed`` and ``recoverSigner`` do this in the ``claimPayment`` function.\n\nThe full contract\n-----------------\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n contract Owned {\n address payable owner;\n constructor() {\n owner = payable(msg.sender);\n }\n }\n\n contract Freezable is Owned {\n bool private _frozen = false;\n\n modifier notFrozen() {\n require(!_frozen, \"Inactive Contract.\");\n _;\n }\n\n function freeze() internal {\n if (msg.sender == owner)\n _frozen = true;\n }\n }\n\n contract ReceiverPays is Freezable {\n mapping(uint256 => bool) usedNonces;\n\n constructor() payable {}\n\n function claimPayment(uint256 amount, uint256 nonce, bytes memory signature)\n external\n notFrozen\n {\n require(!usedNonces[nonce]);\n usedNonces[nonce] = true;\n\n // this recreates the message that was signed on the client\n bytes32 message = prefixed(keccak256(abi.encodePacked(msg.sender, amount, nonce, this)));\n require(recoverSigner(message, signature) == owner);\n (bool success, ) = payable(msg.sender).call{value: amount}(\"\");\n require(success);\n }\n\n /// freeze the contract and reclaim the leftover funds.\n function shutdown()\n external\n notFrozen\n {\n require(msg.sender == owner);\n freeze();\n (bool success, ) = payable(msg.sender).call{value: address(this).balance}(\"\");\n require(success);\n }\n\n /// signature methods.\n function splitSignature(bytes memory sig)\n internal\n pure\n returns (uint8 v, bytes32 r, bytes32 s)\n {\n require(sig.length == 65);\n\n assembly {\n // first 32 bytes, after the length prefix.\n r := mload(add(sig, 32))\n // second 32 bytes.\n s := mload(add(sig, 64))\n // final byte (first byte of the next 32 bytes).\n v := byte(0, mload(add(sig, 96)))\n }\n\n return (v, r, s);\n }\n\n function recoverSigner(bytes32 message, bytes memory sig)\n internal\n pure\n returns (address)\n {\n (uint8 v, bytes32 r, bytes32 s) = splitSignature(sig);\n return ecrecover(message, v, r, s);\n }\n\n /// builds a prefixed hash to mimic the behavior of eth_sign.\n function prefixed(bytes32 hash) internal pure returns (bytes32) {\n return keccak256(abi.encodePacked(\"\\x19Ethereum Signed Message:\\n32\", hash));\n }\n }\n\n\nWriting a Simple Payment Channel\n================================\n\nAlice now builds a simple but complete implementation of a payment\nchannel. Payment channels use cryptographic signatures to make\nrepeated transfers of Ether securely, instantaneously, and without transaction fees.\n\nWhat is a Payment Channel?\n--------------------------\n\nPayment channels allow participants to make repeated transfers of Ether\nwithout using transactions. This means that you can avoid the delays and\nfees associated with transactions. We are going to explore a simple\nunidirectional payment channel between two parties (Alice and Bob). It involves three steps:\n\n 1. Alice funds a smart contract with Ether. This \"opens\" the payment channel.\n 2. Alice signs messages that specify how much of that Ether is owed to the recipient. This step is repeated for each payment.\n 3. Bob \"closes\" the payment channel, withdrawing his portion of the Ether and sending the remainder back to the sender.\n\n.. note::\n Only steps 1 and 3 require Ethereum transactions, step 2 means that the sender\n transmits a cryptographically signed message to the recipient via off chain\n methods (e.g. email). This means only two transactions are required to support\n any number of transfers.\n\nBob is guaranteed to receive his funds because the smart contract escrows the\nEther and honours a valid signed message. The smart contract also enforces a\ntimeout, so Alice is guaranteed to eventually recover her funds even if the\nrecipient refuses to close the channel. It is up to the participants in a payment\nchannel to decide how long to keep it open. For a short-lived transaction,\nsuch as paying an internet café for each minute of network access, the payment\nchannel may be kept open for a limited duration. On the other hand, for a\nrecurring payment, such as paying an employee an hourly wage, the payment channel\nmay be kept open for several months or years.\n\nOpening the Payment Channel\n---------------------------\n\nTo open the payment channel, Alice deploys the smart contract, attaching\nthe Ether to be escrowed and specifying the intended recipient and a\nmaximum duration for the channel to exist. This is the ``constructor``\nin the ``SimplePaymentChannel`` contract, at the end of this section.\n\nMaking Payments\n---------------\n\nAlice makes payments by sending signed messages to Bob.\nThis step is performed entirely outside of the Ethereum network.\nMessages are cryptographically signed by the sender and then transmitted directly to the recipient.\n\nEach message includes the following information:\n\n * The smart contract's address, used to prevent cross-contract replay attacks.\n * The total amount of Ether that is owed to the recipient so far.\n\nA payment channel is closed just once, at the end of a series of transfers.\nBecause of this, only one of the messages sent is redeemed. This is why\neach message specifies a cumulative total amount of Ether owed, rather than the\namount of the individual micropayment. The recipient will naturally choose to\nredeem the most recent message because that is the one with the highest total.\nThe nonce per-message is not needed anymore, because the smart contract only\nhonours a single message. The address of the smart contract is still used\nto prevent a message intended for one payment channel from being used for a different channel.\n\nHere is the modified JavaScript code to cryptographically sign a message from the previous section:\n\n.. code-block:: javascript\n\n function constructPaymentMessage(contractAddress, amount) {\n return abi.soliditySHA3(\n [\"address\", \"uint256\"],\n [contractAddress, amount]\n );\n }\n\n function signMessage(message, callback) {\n web3.eth.personal.sign(\n \"0x\" + message.toString(\"hex\"),\n web3.eth.defaultAccount,\n callback\n );\n }\n\n // contractAddress is used to prevent cross-contract replay attacks.\n // amount, in wei, specifies how much Ether should be sent.\n\n function signPayment(contractAddress, amount, callback) {\n var message = constructPaymentMessage(contractAddress, amount);\n signMessage(message, callback);\n }\n\n\nClosing the Payment Channel\n---------------------------\n\nWhen Bob is ready to receive his funds, it is time to\nclose the payment channel by calling a ``close`` function on the smart contract.\nClosing the channel pays the recipient the Ether they are owed and\ndeactivates the contract by freezing it, sending any remaining Ether back to Alice. To\nclose the channel, Bob needs to provide a message signed by Alice.\n\nThe smart contract must verify that the message contains a valid signature from the sender.\nThe process for doing this verification is the same as the process the recipient uses.\nThe Solidity functions ``isValidSignature`` and ``recoverSigner`` work just like their\nJavaScript counterparts in the previous section, with the latter function borrowed from the ``ReceiverPays`` contract.\n\nOnly the payment channel recipient can call the ``close`` function,\nwho naturally passes the most recent payment message because that message\ncarries the highest total owed. If the sender were allowed to call this function,\nthey could provide a message with a lower amount and cheat the recipient out of what they are owed.\n\nThe function verifies the signed message matches the given parameters.\nIf everything checks out, the recipient is sent their portion of the Ether,\nand the sender is sent the remaining funds via a ``transfer``.\nYou can see the ``close`` function in the full contract.\n\nChannel Expiration\n-------------------\n\nBob can close the payment channel at any time, but if they fail to do so,\nAlice needs a way to recover her escrowed funds. An *expiration* time was set\nat the time of contract deployment. Once that time is reached, Alice can call\n``claimTimeout`` to recover her funds. You can see the ``claimTimeout`` function in the full contract.\n\nAfter this function is called, Bob can no longer receive any Ether,\nso it is important that Bob closes the channel before the expiration is reached.\n\nThe full contract\n-----------------\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n\n contract Frozeable {\n bool private _frozen = false;\n\n modifier notFrozen() {\n require(!_frozen, \"Inactive Contract.\");\n _;\n }\n\n function freeze() internal {\n _frozen = true;\n }\n }\n\n contract SimplePaymentChannel is Frozeable {\n address payable public sender; // The account sending payments.\n address payable public recipient; // The account receiving the payments.\n uint256 public expiration; // Timeout in case the recipient never closes.\n\n constructor (address payable recipientAddress, uint256 duration)\n payable\n {\n sender = payable(msg.sender);\n recipient = recipientAddress;\n expiration = block.timestamp + duration;\n }\n\n /// the recipient can close the channel at any time by presenting a\n /// signed amount from the sender. the recipient will be sent that amount,\n /// and the remainder will go back to the sender\n function close(uint256 amount, bytes memory signature)\n external\n notFrozen\n {\n require(msg.sender == recipient);\n require(isValidSignature(amount, signature));\n\n freeze();\n (bool success, ) = recipient.call{value: amount}(\"\");\n require(success);\n (success, ) = sender.call{value: address(this).balance}(\"\");\n require(success);\n }\n\n /// the sender can extend the expiration at any time\n function extend(uint256 newExpiration)\n external\n notFrozen\n {\n require(msg.sender == sender);\n require(newExpiration > expiration);\n\n expiration = newExpiration;\n }\n\n /// if the timeout is reached without the recipient closing the channel,\n /// then the Ether is released back to the sender.\n function claimTimeout()\n external\n notFrozen\n {\n require(block.timestamp >= expiration);\n freeze();\n (bool success, ) = sender.call{value: address(this).balance}(\"\");\n require(success);\n }\n\n function isValidSignature(uint256 amount, bytes memory signature)\n internal\n view\n returns (bool)\n {\n bytes32 message = prefixed(keccak256(abi.encodePacked(this, amount)));\n // check that the signature is from the payment sender\n return recoverSigner(message, signature) == sender;\n }\n\n /// All functions below this are just taken from the chapter\n /// 'creating and verifying signatures' chapter.\n function splitSignature(bytes memory sig)\n internal\n pure\n returns (uint8 v, bytes32 r, bytes32 s)\n {\n require(sig.length == 65);\n\n assembly {\n // first 32 bytes, after the length prefix\n r := mload(add(sig, 32))\n // second 32 bytes\n s := mload(add(sig, 64))\n // final byte (first byte of the next 32 bytes)\n v := byte(0, mload(add(sig, 96)))\n }\n return (v, r, s);\n }\n\n function recoverSigner(bytes32 message, bytes memory sig)\n internal\n pure\n returns (address)\n {\n (uint8 v, bytes32 r, bytes32 s) = splitSignature(sig);\n return ecrecover(message, v, r, s);\n }\n\n /// builds a prefixed hash to mimic the behavior of eth_sign.\n function prefixed(bytes32 hash) internal pure returns (bytes32) {\n return keccak256(abi.encodePacked(\"\\x19Ethereum Signed Message:\\n32\", hash));\n }\n }\n\n\n.. note::\n The function ``splitSignature`` does not use all security\n checks. A real implementation should use a more rigorously tested library,\n such as openzeppelin's `version `_ of this code.\n\nVerifying Payments\n------------------\n\nUnlike in the previous section, messages in a payment channel aren't\nredeemed right away. The recipient keeps track of the latest message and\nredeems it when it's time to close the payment channel. This means it's\ncritical that the recipient perform their own verification of each message.\nOtherwise there is no guarantee that the recipient will be able to get paid\nin the end.\n\nThe recipient should verify each message using the following process:\n\n 1. Verify that the contract address in the message matches the payment channel.\n 2. Verify that the new total is the expected amount.\n 3. Verify that the new total does not exceed the amount of Ether escrowed.\n 4. Verify that the signature is valid and comes from the payment channel sender.\n\nWe'll use the `ethereumjs-util `_\nlibrary to write this verification. The final step can be done a number of ways,\nand we use JavaScript. The following code borrows the ``constructPaymentMessage`` function from the signing **JavaScript code** above:\n\n.. code-block:: javascript\n\n // this mimics the prefixing behavior of the eth_sign JSON-RPC method.\n function prefixed(hash) {\n return ethereumjs.ABI.soliditySHA3(\n [\"string\", \"bytes32\"],\n [\"\\x19Ethereum Signed Message:\\n32\", hash]\n );\n }\n\n function recoverSigner(message, signature) {\n var split = ethereumjs.Util.fromRpcSig(signature);\n var publicKey = ethereumjs.Util.ecrecover(message, split.v, split.r, split.s);\n var signer = ethereumjs.Util.pubToAddress(publicKey).toString(\"hex\");\n return signer;\n }\n\n function isValidSignature(contractAddress, amount, signature, expectedSigner) {\n var message = prefixed(constructPaymentMessage(contractAddress, amount));\n var signer = recoverSigner(message, signature);\n return signer.toLowerCase() ==\n ethereumjs.Util.stripHexPrefix(expectedSigner).toLowerCase();\n }\n" }, { "path": "docs/examples/modular.rst", "content": ".. index:: contract;modular, modular contract\n\n*****************\nModular Contracts\n*****************\n\nA modular approach to building your contracts helps you reduce the complexity\nand improve the readability which will help to identify bugs and vulnerabilities\nduring development and code review.\nIf you specify and control the behavior of each module in isolation, the\ninteractions you have to consider are only those between the module specifications\nand not every other moving part of the contract.\nIn the example below, the contract uses the ``move`` method\nof the ``Balances`` :ref:`library ` to check that balances sent between\naddresses match what you expect. In this way, the ``Balances`` library\nprovides an isolated component that properly tracks balances of accounts.\nIt is easy to verify that the ``Balances`` library never produces negative balances or overflows\nand the sum of all balances is an invariant across the lifetime of the contract.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.5.0 <0.9.0;\n\n library Balances {\n function move(mapping(address => uint256) storage balances, address from, address to, uint amount) internal {\n require(balances[from] >= amount);\n require(balances[to] + amount >= balances[to]);\n balances[from] -= amount;\n balances[to] += amount;\n }\n }\n\n contract Token {\n mapping(address => uint256) balances;\n using Balances for *;\n mapping(address => mapping(address => uint256)) allowed;\n\n event Transfer(address from, address to, uint amount);\n event Approval(address owner, address spender, uint amount);\n\n function transfer(address to, uint amount) external returns (bool success) {\n balances.move(msg.sender, to, amount);\n emit Transfer(msg.sender, to, amount);\n return true;\n\n }\n\n function transferFrom(address from, address to, uint amount) external returns (bool success) {\n require(allowed[from][msg.sender] >= amount);\n allowed[from][msg.sender] -= amount;\n balances.move(from, to, amount);\n emit Transfer(from, to, amount);\n return true;\n }\n\n function approve(address spender, uint tokens) external returns (bool success) {\n require(allowed[msg.sender][spender] == 0, \"\");\n allowed[msg.sender][spender] = tokens;\n emit Approval(msg.sender, spender, tokens);\n return true;\n }\n\n function balanceOf(address tokenOwner) external view returns (uint balance) {\n return balances[tokenOwner];\n }\n }\n" }, { "path": "docs/examples/safe-remote.rst", "content": ".. index:: purchase, remote purchase, escrow\n\n********************\nSafe Remote Purchase\n********************\n\nPurchasing goods remotely currently requires multiple parties that need to trust each other.\nThe simplest configuration involves a seller and a buyer. The buyer would like to receive\nan item from the seller and the seller would like to get some compensation, e.g. Ether,\nin return. The problematic part is the shipment here: There is no way to determine for\nsure that the item arrived at the buyer.\n\nThere are multiple ways to solve this problem, but all fall short in one or the other way.\nIn the following example, both parties have to put twice the value of the item into the\ncontract as escrow. As soon as this happened, the Ether will stay locked inside\nthe contract until the buyer confirms that they received the item. After that,\nthe buyer is returned the value (half of their deposit) and the seller gets three\ntimes the value (their deposit plus the value). The idea behind\nthis is that both parties have an incentive to resolve the situation or otherwise\ntheir Ether is locked forever.\n\nThis contract of course does not solve the problem, but gives an overview of how\nyou can use state machine-like constructs inside a contract.\n\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.4;\n contract Purchase {\n uint public value;\n address payable public seller;\n address payable public buyer;\n\n enum State { Created, Locked, Release, Inactive }\n // The state variable has a default value of the first member, `State.created`\n State public state;\n\n modifier condition(bool condition_) {\n require(condition_);\n _;\n }\n\n /// Only the buyer can call this function.\n error OnlyBuyer();\n /// Only the seller can call this function.\n error OnlySeller();\n /// The function cannot be called at the current state.\n error InvalidState();\n /// The provided value has to be even.\n error ValueNotEven();\n\n modifier onlyBuyer() {\n if (msg.sender != buyer)\n revert OnlyBuyer();\n _;\n }\n\n modifier onlySeller() {\n if (msg.sender != seller)\n revert OnlySeller();\n _;\n }\n\n modifier inState(State state_) {\n if (state != state_)\n revert InvalidState();\n _;\n }\n\n event Aborted();\n event PurchaseConfirmed();\n event ItemReceived();\n event SellerRefunded();\n\n // Ensure that `msg.value` is an even number.\n // Division will truncate if it is an odd number.\n // Check via multiplication that it wasn't an odd number.\n constructor() payable {\n seller = payable(msg.sender);\n value = msg.value / 2;\n if ((2 * value) != msg.value)\n revert ValueNotEven();\n }\n\n /// Abort the purchase and reclaim the ether.\n /// Can only be called by the seller before\n /// the contract is locked.\n function abort()\n external\n onlySeller\n inState(State.Created)\n {\n emit Aborted();\n state = State.Inactive;\n // We use call here directly. It is\n // reentrancy-safe, because it is the\n // last call in this function and we\n // already changed the state.\n (bool success, ) = seller.call{value: address(this).balance}(\"\");\n require(success);\n }\n\n /// Confirm the purchase as buyer.\n /// Transaction has to include `2 * value` ether.\n /// The ether will be locked until confirmReceived\n /// is called.\n function confirmPurchase()\n external\n inState(State.Created)\n condition(msg.value == (2 * value))\n payable\n {\n emit PurchaseConfirmed();\n buyer = payable(msg.sender);\n state = State.Locked;\n }\n\n /// Confirm that you (the buyer) received the item.\n /// This will release the locked ether.\n function confirmReceived()\n external\n onlyBuyer\n inState(State.Locked)\n {\n emit ItemReceived();\n // It is important to change the state first because\n // otherwise, the contracts called using `call` below\n // can call in again here.\n state = State.Release;\n\n (bool success, ) = buyer.call{value: value}(\"\");\n require(success);\n }\n\n /// This function refunds the seller, i.e.\n /// pays back the locked funds of the seller.\n function refundSeller()\n external\n onlySeller\n inState(State.Release)\n {\n emit SellerRefunded();\n // It is important to change the state first because\n // otherwise, the contracts called using `call` below\n // can call in again here.\n state = State.Inactive;\n\n (bool success, ) = seller.call{value: 3 * value}(\"\");\n require(success);\n }\n }\n" }, { "path": "docs/examples/voting.rst", "content": ".. index:: voting, ballot\n\n.. _voting:\n\n******\nVoting\n******\n\nThe following contract is quite complex, but showcases\na lot of Solidity's features. It implements a voting\ncontract. Of course, the main problems of electronic\nvoting is how to assign voting rights to the correct\npersons and how to prevent manipulation. We will not\nsolve all problems here, but at least we will show\nhow delegated voting can be done so that vote counting\nis **automatic and completely transparent** at the\nsame time.\n\nThe idea is to create one contract per ballot,\nproviding a short name for each option.\nThen the creator of the contract who serves as\nchairperson will give the right to vote to each\naddress individually.\n\nThe persons behind the addresses can then choose\nto either vote themselves or to delegate their\nvote to a person they trust.\n\nAt the end of the voting time, ``winningProposal()``\nwill return the proposal with the largest number\nof votes.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n /// @title Voting with delegation.\n contract Ballot {\n // This declares a new complex type which will\n // be used for variables later.\n // It will represent a single voter.\n struct Voter {\n uint weight; // weight is accumulated by delegation\n bool voted; // if true, that person already voted\n address delegate; // person delegated to\n uint vote; // index of the voted proposal\n }\n\n // This is a type for a single proposal.\n struct Proposal {\n bytes32 name; // short name (up to 32 bytes)\n uint voteCount; // number of accumulated votes\n }\n\n address public chairperson;\n\n // This declares a state variable that\n // stores a `Voter` struct for each possible address.\n mapping(address => Voter) public voters;\n\n // A dynamically-sized array of `Proposal` structs.\n Proposal[] public proposals;\n\n /// Create a new ballot to choose one of `proposalNames`.\n constructor(bytes32[] memory proposalNames) {\n chairperson = msg.sender;\n voters[chairperson].weight = 1;\n\n // For each of the provided proposal names,\n // create a new proposal object and add it\n // to the end of the array.\n for (uint i = 0; i < proposalNames.length; i++) {\n // `Proposal({...})` creates a temporary\n // Proposal object and `proposals.push(...)`\n // appends it to the end of `proposals`.\n proposals.push(Proposal({\n name: proposalNames[i],\n voteCount: 0\n }));\n }\n }\n\n // Give `voter` the right to vote on this ballot.\n // May only be called by `chairperson`.\n function giveRightToVote(address voter) external {\n // If the first argument of `require` evaluates\n // to `false`, execution terminates and all\n // changes to the state and to Ether balances\n // are reverted.\n // This used to consume all gas in old EVM versions, but\n // not anymore.\n // It is often a good idea to use `require` to check if\n // functions are called correctly.\n // As a second argument, you can also provide an\n // explanation about what went wrong.\n require(\n msg.sender == chairperson,\n \"Only chairperson can give right to vote.\"\n );\n require(\n !voters[voter].voted,\n \"The voter already voted.\"\n );\n require(voters[voter].weight == 0);\n voters[voter].weight = 1;\n }\n\n /// Delegate your vote to the voter `to`.\n function delegate(address to) external {\n // assigns reference\n Voter storage sender = voters[msg.sender];\n require(sender.weight != 0, \"You have no right to vote\");\n require(!sender.voted, \"You already voted.\");\n\n require(to != msg.sender, \"Self-delegation is disallowed.\");\n\n // Forward the delegation as long as\n // `to` also delegated.\n // In general, such loops are very dangerous,\n // because if they run too long, they might\n // need more gas than is available in a block.\n // In this case, the delegation will not be executed,\n // but in other situations, such loops might\n // cause a contract to get \"stuck\" completely.\n while (voters[to].delegate != address(0)) {\n to = voters[to].delegate;\n\n // We found a loop in the delegation, not allowed.\n require(to != msg.sender, \"Found loop in delegation.\");\n }\n\n Voter storage delegate_ = voters[to];\n\n // Voters cannot delegate to accounts that cannot vote.\n require(delegate_.weight >= 1);\n\n // Since `sender` is a reference, this\n // modifies `voters[msg.sender]`.\n sender.voted = true;\n sender.delegate = to;\n\n if (delegate_.voted) {\n // If the delegate already voted,\n // directly add to the number of votes\n proposals[delegate_.vote].voteCount += sender.weight;\n } else {\n // If the delegate did not vote yet,\n // add to her weight.\n delegate_.weight += sender.weight;\n }\n }\n\n /// Give your vote (including votes delegated to you)\n /// to proposal `proposals[proposal].name`.\n function vote(uint proposal) external {\n Voter storage sender = voters[msg.sender];\n require(sender.weight != 0, \"Has no right to vote\");\n require(!sender.voted, \"Already voted.\");\n sender.voted = true;\n sender.vote = proposal;\n\n // If `proposal` is out of the range of the array,\n // this will throw automatically and revert all\n // changes.\n proposals[proposal].voteCount += sender.weight;\n }\n\n /// @dev Computes the winning proposal taking all\n /// previous votes into account.\n function winningProposal() public view\n returns (uint winningProposal_)\n {\n uint winningVoteCount = 0;\n for (uint p = 0; p < proposals.length; p++) {\n if (proposals[p].voteCount > winningVoteCount) {\n winningVoteCount = proposals[p].voteCount;\n winningProposal_ = p;\n }\n }\n }\n\n // Calls winningProposal() function to get the index\n // of the winner contained in the proposals array and then\n // returns the name of the winner\n function winnerName() external view\n returns (bytes32 winnerName_)\n {\n winnerName_ = proposals[winningProposal()].name;\n }\n }\n\n\nPossible Improvements\n=====================\n\nCurrently, many transactions are needed to\nassign the rights to vote to all participants.\nMoreover, if two or more proposals have the same\nnumber of votes, ``winningProposal()`` is not able\nto register a tie. Can you think of a way to fix these issues?" }, { "path": "docs/ext/html_extra_template_renderer.py", "content": "import os.path\n\n\ndef render_html_extra_templates(app):\n if app.builder.format != 'html':\n # Non-HTML builders do not provide .templates.render_string(). Note that a HTML\n # builder is still used also when building some other formats like json or epub.\n return\n\n for input_path, template_config in app.config.html_extra_templates.items():\n # Requiring absolute paths simplifies the implementation.\n if not os.path.isabs(input_path):\n raise RuntimeError(f\"Template input path is not absolute: {input_path}\")\n if not os.path.isabs(template_config['target']):\n raise RuntimeError(f\"Template target path is not absolute: {template_config['target']}\")\n\n with open(input_path, 'r', encoding='utf8') as input_file:\n # This runs Jinja2, which supports rendering {{ }} tags among other things.\n rendered_template = app.builder.templates.render_string(\n input_file.read(),\n template_config['context'],\n )\n\n with open(template_config['target'], 'w', encoding='utf8') as target_file:\n target_file.write(rendered_template)\n\n app.config.html_extra_path.append(template_config['target'])\n\n\ndef setup(app):\n app.add_config_value('html_extra_templates', default={}, rebuild='', types=dict)\n\n # Register a handler for the env-before-read-docs event. Any event that's fired before static\n # files get copied would do.\n app.connect(\n 'env-before-read-docs',\n lambda app, env, docnames: render_html_extra_templates(app)\n )\n\n return {\n # NOTE: Need to access _raw_config here because setup() runs before app.config is ready.\n 'version': app.config._raw_config['version'], # pylint: disable=protected-access\n 'parallel_read_safe': True,\n 'parallel_write_safe': True,\n }\n" }, { "path": "docs/ext/remix_code_links.py", "content": "import base64\nimport docutils # pragma pylint: disable=import-error\n\nfrom sphinx.util import logging # pragma pylint: disable=import-error\n\n# NOTE: 2000 should generally be safe for all browsers, while 8000 for most of them.\nMAX_SAFE_URL_LENGTH = 10000\n\nlogger = logging.getLogger(__name__)\n\n\ndef insert_node_before(child, new_sibling):\n assert child in child.parent.children\n\n for position, node in enumerate(child.parent.children):\n if node == child:\n child.parent.insert(position, new_sibling)\n break\n\n\ndef remix_code_url(source_code, language, solidity_version):\n # NOTE: base64 encoded data may contain +, = and / characters. Remix seems to handle them just\n # fine without any escaping.\n base64_encoded_source = base64.b64encode(source_code.encode('utf-8')).decode('ascii')\n return f\"https://remix.ethereum.org/?#language={language}&version={solidity_version}&code={base64_encoded_source}\"\n\n\ndef build_remix_link_node(url):\n reference_node = docutils.nodes.reference('', 'open in Remix', internal=False, refuri=url, target='_blank')\n reference_node['classes'].append('remix-link')\n\n paragraph_node = docutils.nodes.paragraph()\n paragraph_node['classes'].append('remix-link-container')\n paragraph_node.append(reference_node)\n return paragraph_node\n\n\ndef insert_remix_link(app, doctree, solidity_version):\n if app.builder.format != 'html' or app.builder.name == 'epub':\n return\n\n for literal_block_node in doctree.traverse(docutils.nodes.literal_block):\n assert 'language' in literal_block_node.attributes\n language = literal_block_node.attributes['language'].lower()\n if language not in ['solidity', 'yul']:\n continue\n\n text_nodes = list(literal_block_node.traverse(docutils.nodes.Text))\n assert len(text_nodes) == 1\n\n remix_url = remix_code_url(text_nodes[0], language, solidity_version)\n url_length = len(remix_url.encode('utf-8'))\n if url_length > MAX_SAFE_URL_LENGTH:\n logger.warning(\n \"Remix URL generated from the code snippet exceeds the maximum safe URL length \"\n \" (%d > %d bytes).\",\n url_length,\n MAX_SAFE_URL_LENGTH,\n location=(literal_block_node.source, literal_block_node.line),\n )\n\n insert_node_before(literal_block_node, build_remix_link_node(remix_url))\n\n\ndef setup(app):\n # NOTE: Need to access _raw_config here because setup() runs before app.config is ready.\n solidity_version = app.config._raw_config['version'] # pylint: disable=protected-access\n\n app.connect(\n 'doctree-resolved',\n lambda app, doctree, docname: insert_remix_link(app, doctree, solidity_version)\n )\n\n return {\n 'version': solidity_version,\n 'parallel_read_safe': True,\n 'parallel_write_safe': True,\n }\n" }, { "path": "docs/grammar/SolidityLexer.g4", "content": "lexer grammar SolidityLexer;\n\n/**\n * Keywords reserved for future use in Solidity.\n */\nReservedKeywords:\n\t'after' | 'alias' | 'apply' | 'auto' | 'byte' | 'case' | 'copyof' | 'default' | 'define' | 'final'\n\t| 'implements' | 'in' | 'inline' | 'let' | 'macro' | 'match' | 'mutable' | 'null' | 'of'\n\t| 'partial' | 'promise' | 'reference' | 'relocatable' | 'sealed' | 'sizeof' | 'static'\n\t| 'supports' | 'switch' | 'typedef' | 'typeof' | 'var';\n\nAbstract: 'abstract';\nAddress: 'address';\nAnonymous: 'anonymous';\nAs: 'as';\nAssembly: 'assembly' -> pushMode(AssemblyBlockMode);\nAt: 'at'; // not a real keyword\nBool: 'bool';\nBreak: 'break';\nBytes: 'bytes';\nCalldata: 'calldata';\nCatch: 'catch';\nConstant: 'constant';\nConstructor: 'constructor';\nContinue: 'continue';\nContract: 'contract';\nDelete: 'delete';\nDo: 'do';\nElse: 'else';\nEmit: 'emit';\nEnum: 'enum';\nError: 'error'; // not a real keyword\nEvent: 'event';\nExternal: 'external';\nFallback: 'fallback';\nFalse: 'false';\nFixed: 'fixed' | ('fixed' [1-9][0-9]* 'x' [1-9][0-9]*);\n/**\n * Bytes types of fixed length.\n */\nFixedBytes:\n\t'bytes1' | 'bytes2' | 'bytes3' | 'bytes4' | 'bytes5' | 'bytes6' | 'bytes7' | 'bytes8' |\n\t'bytes9' | 'bytes10' | 'bytes11' | 'bytes12' | 'bytes13' | 'bytes14' | 'bytes15' | 'bytes16' |\n\t'bytes17' | 'bytes18' | 'bytes19' | 'bytes20' | 'bytes21' | 'bytes22' | 'bytes23' | 'bytes24' |\n\t'bytes25' | 'bytes26' | 'bytes27' | 'bytes28' | 'bytes29' | 'bytes30' | 'bytes31' | 'bytes32';\nFor: 'for';\nFrom: 'from'; // not a real keyword\nFunction: 'function';\nGlobal: 'global'; // not a real keyword\nHex: 'hex';\nIf: 'if';\nImmutable: 'immutable';\nImport: 'import';\nIndexed: 'indexed';\nInterface: 'interface';\nInternal: 'internal';\nIs: 'is';\nLayout: 'layout'; // not a real keyword\nLibrary: 'library';\nMapping: 'mapping';\nMemory: 'memory';\nModifier: 'modifier';\nNew: 'new';\n/**\n * Unit denomination for numbers.\n */\nSubDenomination: 'wei' | 'gwei' | 'ether' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'years';\nOverride: 'override';\nPayable: 'payable';\nPragma: 'pragma' -> pushMode(PragmaMode);\nPrivate: 'private';\nPublic: 'public';\nPure: 'pure';\nReceive: 'receive';\nReturn: 'return';\nReturns: 'returns';\nRevert: 'revert'; // not a real keyword\n/**\n * Sized signed integer types.\n * int is an alias of int256.\n */\nSignedIntegerType:\n\t'int' | 'int8' | 'int16' | 'int24' | 'int32' | 'int40' | 'int48' | 'int56' | 'int64' |\n\t'int72' | 'int80' | 'int88' | 'int96' | 'int104' | 'int112' | 'int120' | 'int128' |\n\t'int136' | 'int144' | 'int152' | 'int160' | 'int168' | 'int176' | 'int184' | 'int192' |\n\t'int200' | 'int208' | 'int216' | 'int224' | 'int232' | 'int240' | 'int248' | 'int256';\nStorage: 'storage';\nString: 'string';\nStruct: 'struct';\nTransient: 'transient'; // not a real keyword\nTrue: 'true';\nTry: 'try';\nType: 'type';\nUfixed: 'ufixed' | ('ufixed' [1-9][0-9]+ 'x' [1-9][0-9]+);\nUnchecked: 'unchecked';\nUnicode: 'unicode';\n/**\n * Sized unsigned integer types.\n * uint is an alias of uint256.\n */\nUnsignedIntegerType:\n\t'uint' | 'uint8' | 'uint16' | 'uint24' | 'uint32' | 'uint40' | 'uint48' | 'uint56' | 'uint64' |\n\t'uint72' | 'uint80' | 'uint88' | 'uint96' | 'uint104' | 'uint112' | 'uint120' | 'uint128' |\n\t'uint136' | 'uint144' | 'uint152' | 'uint160' | 'uint168' | 'uint176' | 'uint184' | 'uint192' |\n\t'uint200' | 'uint208' | 'uint216' | 'uint224' | 'uint232' | 'uint240' | 'uint248' | 'uint256';\nUsing: 'using';\nView: 'view';\nVirtual: 'virtual';\nWhile: 'while';\n\nLParen: '(';\nRParen: ')';\nLBrack: '[';\nRBrack: ']';\nLBrace: '{';\nRBrace: '}';\nColon: ':';\nSemicolon: ';';\nPeriod: '.';\nConditional: '?';\nDoubleArrow: '=>';\nRightArrow: '->';\n\nAssign: '=';\nAssignBitOr: '|=';\nAssignBitXor: '^=';\nAssignBitAnd: '&=';\nAssignShl: '<<=';\nAssignSar: '>>=';\nAssignShr: '>>>=';\nAssignAdd: '+=';\nAssignSub: '-=';\nAssignMul: '*=';\nAssignDiv: '/=';\nAssignMod: '%=';\n\nComma: ',';\nOr: '||';\nAnd: '&&';\nBitOr: '|';\nBitXor: '^';\nBitAnd: '&';\nShl: '<<';\nSar: '>>';\nShr: '>>>';\nAdd: '+';\nSub: '-';\nMul: '*';\nDiv: '/';\nMod: '%';\nExp: '**';\n\nEqual: '==';\nNotEqual: '!=';\nLessThan: '<';\nGreaterThan: '>';\nLessThanOrEqual: '<=';\nGreaterThanOrEqual: '>=';\nNot: '!';\nBitNot: '~';\nInc: '++';\nDec: '--';\n//@doc:inline\nDoubleQuote: '\"';\n//@doc:inline\nSingleQuote: '\\'';\n\n/**\n * A non-empty quoted string literal restricted to printable characters.\n */\nNonEmptyStringLiteral: '\"' DoubleQuotedStringCharacter+ '\"' | '\\'' SingleQuotedStringCharacter+ '\\'';\n/**\n * An empty string literal\n */\nEmptyStringLiteral: '\"' '\"' | '\\'' '\\'';\n\n// Note that this will also be used for Yul string literals.\n//@doc:inline\nfragment DoubleQuotedStringCharacter: DoubleQuotedPrintable | EscapeSequence;\n// Note that this will also be used for Yul string literals.\n//@doc:inline\nfragment SingleQuotedStringCharacter: SingleQuotedPrintable | EscapeSequence;\n/**\n * Any printable character except single quote or back slash.\n */\nfragment SingleQuotedPrintable: [\\u0020-\\u0026\\u0028-\\u005B\\u005D-\\u007E];\n/**\n * Any printable character except double quote or back slash.\n */\nfragment DoubleQuotedPrintable: [\\u0020-\\u0021\\u0023-\\u005B\\u005D-\\u007E];\n/**\n * Escape sequence.\n * Apart from common single character escape sequences, line breaks can be escaped\n * as well as four hex digit unicode escapes \\\\uXXXX and two digit hex escape sequences \\\\xXX are allowed.\n */\nfragment EscapeSequence:\n\t'\\\\' (\n\t\t['\"\\\\nrt\\n\\r]\n\t\t| 'u' HexCharacter HexCharacter HexCharacter HexCharacter\n\t\t| 'x' HexCharacter HexCharacter\n\t);\n/**\n * A single quoted string literal allowing arbitrary unicode characters.\n */\nUnicodeStringLiteral: 'unicode' (('\"' DoubleQuotedUnicodeStringCharacter* '\"') | ('\\'' SingleQuotedUnicodeStringCharacter* '\\''));\n//@doc:inline\nfragment DoubleQuotedUnicodeStringCharacter: ~[\"\\r\\n\\\\] | EscapeSequence;\n//@doc:inline\nfragment SingleQuotedUnicodeStringCharacter: ~['\\r\\n\\\\] | EscapeSequence;\n\n// Note that this will also be used for Yul hex string literals.\n/**\n * Hex strings need to consist of an even number of hex digits that may be grouped using underscores.\n */\nHexString: 'hex' (('\"' EvenHexDigits? '\"') | ('\\'' EvenHexDigits? '\\''));\n/**\n * Hex numbers consist of a prefix and an arbitrary number of hex digits that may be delimited by underscores.\n */\nHexNumber: '0' 'x' HexDigits;\n//@doc:inline\nfragment HexDigits: HexCharacter ('_'? HexCharacter)*;\n//@doc:inline\nfragment EvenHexDigits: HexCharacter HexCharacter ('_'? HexCharacter HexCharacter)*;\n//@doc:inline\nfragment HexCharacter: [0-9A-Fa-f];\n\n/**\n * Scanned but not used by any rule, i.e, disallowed.\n * solc parser considers number starting with '0', not immediately followed by '.' or 'x' as\n * octal, even if non octal digits '8' and '9' are present.\n */\nOctalNumber: '0' DecimalDigits ('.' DecimalDigits)?;\n\n\n/**\n * A decimal number literal consists of decimal digits that may be delimited by underscores and\n * an optional positive or negative exponent.\n * If the digits contain a decimal point, the literal has fixed point type.\n */\nDecimalNumber: (DecimalDigits | (DecimalDigits? '.' DecimalDigits)) ([eE] '-'? DecimalDigits)?;\n//@doc:inline\nfragment DecimalDigits: [0-9] ('_'? [0-9])* ;\n\n\n/**\n * This is needed to avoid successfully parsing a number followed by a string with no whitespace between.\n */\nDecimalNumberFollowedByIdentifier: DecimalNumber Identifier;\n\n\n/**\n * An identifier in solidity has to start with a letter, a dollar-sign or an underscore and\n * may additionally contain numbers after the first symbol.\n */\nIdentifier: IdentifierStart IdentifierPart*;\n//@doc:inline\nfragment IdentifierStart: [a-zA-Z$_];\n//@doc:inline\nfragment IdentifierPart: [a-zA-Z0-9$_];\n\nWS: [ \\t\\r\\n\\u000C]+ -> skip ;\nCOMMENT: '/*' .*? '*/' -> channel(HIDDEN) ;\nLINE_COMMENT: '//' ~[\\r\\n]* -> channel(HIDDEN);\n\nmode AssemblyBlockMode;\n\n//@doc:inline\nAssemblyDialect: '\"evmasm\"';\nAssemblyLBrace: '{' -> popMode, pushMode(YulMode);\n\nAssemblyFlagString: '\"' DoubleQuotedStringCharacter+ '\"';\n\nAssemblyBlockLParen: '(';\nAssemblyBlockRParen: ')';\nAssemblyBlockComma: ',';\n\nAssemblyBlockWS: [ \\t\\r\\n\\u000C]+ -> skip ;\nAssemblyBlockCOMMENT: '/*' .*? '*/' -> channel(HIDDEN) ;\nAssemblyBlockLINE_COMMENT: '//' ~[\\r\\n]* -> channel(HIDDEN) ;\n\nmode YulMode;\n\nYulBreak: 'break';\nYulCase: 'case';\nYulContinue: 'continue';\nYulDefault: 'default';\nYulFalse: 'false';\nYulFor: 'for';\nYulFunction: 'function';\nYulIf: 'if';\nYulLeave: 'leave';\nYulLet: 'let';\nYulSwitch: 'switch';\nYulTrue: 'true';\nYulHex: 'hex';\n\n/**\n * Builtin functions in the EVM Yul dialect.\n */\nYulEVMBuiltin:\n\t'stop' | 'add' | 'sub' | 'mul' | 'div' | 'sdiv' | 'mod' | 'smod' | 'exp' | 'not'\n\t| 'lt' | 'gt' | 'slt' | 'sgt' | 'eq' | 'iszero' | 'and' | 'or' | 'xor' | 'byte'\n\t| 'shl' | 'shr' | 'sar' | 'clz' | 'addmod' | 'mulmod' | 'signextend' | 'keccak256'\n\t| 'pop' | 'mload' | 'mstore' | 'mstore8' | 'sload' | 'sstore' | 'tload' | 'tstore'| 'msize' | 'gas'\n\t| 'address' | 'balance' | 'selfbalance' | 'caller' | 'callvalue' | 'calldataload'\n\t| 'calldatasize' | 'calldatacopy' | 'extcodesize' | 'extcodecopy' | 'returndatasize'\n\t| 'returndatacopy' | 'mcopy' | 'extcodehash' | 'create' | 'create2' | 'call' | 'callcode'\n\t| 'delegatecall' | 'staticcall' | 'return' | 'revert' | 'selfdestruct' | 'invalid'\n\t| 'log0' | 'log1' | 'log2' | 'log3' | 'log4' | 'chainid' | 'origin' | 'gasprice'\n\t| 'blockhash' | 'blobhash' | 'coinbase' | 'timestamp' | 'number' | 'difficulty'\n\t| 'prevrandao' | 'gaslimit' | 'basefee' | 'blobbasefee';\n\nYulLBrace: '{' -> pushMode(YulMode);\nYulRBrace: '}' -> popMode;\nYulLParen: '(';\nYulRParen: ')';\nYulAssign: ':=';\nYulPeriod: '.';\nYulComma: ',';\nYulArrow: '->';\n\n/**\n * Yul identifiers consist of letters, dollar signs, underscores and numbers, but may not start with a number.\n * In inline assembly there cannot be dots in user-defined identifiers. Instead see yulPath for expressions\n * consisting of identifiers with dots.\n */\nYulIdentifier: YulIdentifierStart YulIdentifierPart*;\n//@doc:inline\nfragment YulIdentifierStart: [a-zA-Z$_];\n//@doc:inline\nfragment YulIdentifierPart: [a-zA-Z0-9$_];\n/**\n * Hex literals in Yul consist of a prefix and one or more hexadecimal digits.\n */\nYulHexNumber: '0' 'x' [0-9a-fA-F]+;\n/**\n * Decimal literals in Yul may be zero or any sequence of decimal digits without leading zeroes.\n */\nYulDecimalNumber: '0' | ([1-9] [0-9]*);\n/**\n * String literals in Yul consist of one or more double-quoted or single-quoted strings\n * that may contain escape sequences and printable characters except unescaped line breaks or\n * unescaped double-quotes or single-quotes, respectively.\n */\nYulStringLiteral:\n\t'\"' DoubleQuotedStringCharacter* '\"'\n\t| '\\'' SingleQuotedStringCharacter* '\\'';\n//@doc:inline\nYulHexStringLiteral: HexString;\n\nYulWS: [ \\t\\r\\n\\u000C]+ -> skip ;\nYulCOMMENT: '/*' .*? '*/' -> channel(HIDDEN) ;\nYulLINE_COMMENT: '//' ~[\\r\\n]* -> channel(HIDDEN) ;\n\nmode PragmaMode;\n\n/**\n * Pragma token. Can contain any kind of symbol except a semicolon.\n * Note that currently the solidity parser only allows a subset of this.\n */\n//@doc:name pragma-token\n//@doc:no-diagram\nPragmaToken: ~[;]+;\nPragmaSemicolon: ';' -> popMode;\n\nPragmaWS: [ \\t\\r\\n\\u000C]+ -> skip ;\nPragmaCOMMENT: '/*' .*? '*/' -> channel(HIDDEN) ;\nPragmaLINE_COMMENT: '//' ~[\\r\\n]* -> channel(HIDDEN) ;\n" }, { "path": "docs/grammar/SolidityParser.g4", "content": "/**\n * Solidity is a statically typed, contract-oriented, high-level language for implementing smart contracts on the Ethereum platform.\n */\nparser grammar SolidityParser;\n\noptions { tokenVocab=SolidityLexer; }\n\n/**\n * On top level, Solidity allows pragmas, import directives, and\n * definitions of contracts, interfaces, libraries, structs, enums and constants.\n */\nsourceUnit: (\n\tpragmaDirective\n\t| importDirective\n\t| usingDirective\n\t| contractDefinition\n\t| interfaceDefinition\n\t| libraryDefinition\n\t| functionDefinition\n\t| constantVariableDeclaration\n\t| structDefinition\n\t| enumDefinition\n\t| userDefinedValueTypeDefinition\n\t| errorDefinition\n\t| eventDefinition\n)* EOF;\n\n//@doc: inline\npragmaDirective: Pragma PragmaToken+ PragmaSemicolon;\n\n/**\n * Import directives import identifiers from different files.\n */\nimportDirective:\n\tImport (\n\t\t(path (As unitAlias=identifier)?)\n\t\t| (symbolAliases From path)\n\t\t| (Mul As unitAlias=identifier From path)\n\t) Semicolon;\n//@doc: inline\n//@doc:name aliases\nimportAliases: symbol=identifier (As alias=identifier)?;\n/**\n * Path of a file to be imported.\n */\npath: NonEmptyStringLiteral;\n/**\n * List of aliases for symbols to be imported.\n */\nsymbolAliases: LBrace aliases+=importAliases (Comma aliases+=importAliases)* RBrace;\n\n/**\n * Top-level definition of a contract.\n */\ncontractDefinition\nlocals [boolean layoutSet=false, boolean inheritanceSet=false]\n:\n\tAbstract? Contract name=identifier\n\t(\n\t\t{!$layoutSet}? Layout At expression {$layoutSet = true;}\n\t\t| {!$inheritanceSet}? inheritanceSpecifierList {$inheritanceSet = true;}\n\t)*\n\tLBrace contractBodyElement* RBrace;\n/**\n * Top-level definition of an interface.\n */\ninterfaceDefinition:\n\tInterface name=identifier\n\tinheritanceSpecifierList?\n\tLBrace contractBodyElement* RBrace;\n/**\n * Top-level definition of a library.\n */\nlibraryDefinition: Library name=identifier LBrace contractBodyElement* RBrace;\n\n//@doc:inline\ninheritanceSpecifierList:\n\tIs inheritanceSpecifiers+=inheritanceSpecifier\n\t(Comma inheritanceSpecifiers+=inheritanceSpecifier)*?;\n/**\n * Inheritance specifier for contracts and interfaces.\n * Can optionally supply base constructor arguments.\n */\ninheritanceSpecifier: name=identifierPath arguments=callArgumentList?;\n\n/**\n * Declarations that can be used in contracts, interfaces and libraries.\n *\n * Note that interfaces and libraries may not contain constructors, interfaces may not contain state variables\n * and libraries may not contain fallback, receive functions nor non-constant state variables.\n */\ncontractBodyElement:\n\tconstructorDefinition\n\t| functionDefinition\n\t| modifierDefinition\n\t| fallbackFunctionDefinition\n\t| receiveFunctionDefinition\n\t| structDefinition\n\t| enumDefinition\n\t| userDefinedValueTypeDefinition\n\t| stateVariableDeclaration\n\t| eventDefinition\n\t| errorDefinition\n\t| usingDirective;\n//@doc:inline\nnamedArgument: name=identifier Colon value=expression;\n/**\n * Arguments when calling a function or a similar callable object.\n * The arguments are either given as comma separated list or as map of named arguments.\n */\ncallArgumentList: LParen ((expression (Comma expression)*)? | LBrace (namedArgument (Comma namedArgument)*)? RBrace) RParen;\n/**\n * Qualified name.\n */\nidentifierPath: identifier (Period identifier)*;\n\n/**\n * Call to a modifier. If the modifier takes no arguments, the argument list can be skipped entirely\n * (including opening and closing parentheses).\n */\nmodifierInvocation: identifierPath callArgumentList?;\n/**\n * Visibility for functions and function types.\n */\nvisibility: Internal | External | Private | Public;\n/**\n * A list of parameters, such as function arguments or return values.\n */\nparameterList: parameters+=parameterDeclaration (Comma parameters+=parameterDeclaration)*;\n//@doc:inline\nparameterDeclaration: type=typeName location=dataLocation? name=identifier?;\n/**\n * Definition of a constructor.\n * Must always supply an implementation.\n * Note that specifying internal or public visibility is deprecated.\n */\nconstructorDefinition\nlocals[boolean payableSet = false, boolean visibilitySet = false]\n:\n\tConstructor LParen (arguments=parameterList)? RParen\n\t(\n\t\tmodifierInvocation\n\t\t| {!$payableSet}? Payable {$payableSet = true;}\n\t\t| {!$visibilitySet}? Internal {$visibilitySet = true;}\n\t\t| {!$visibilitySet}? Public {$visibilitySet = true;}\n\t)*\n\tbody=block;\n\n/**\n * State mutability for function types.\n * The default mutability 'non-payable' is assumed if no mutability is specified.\n */\nstateMutability: Pure | View | Payable;\n/**\n * An override specifier used for functions, modifiers or state variables.\n * In cases where there are ambiguous declarations in several base contracts being overridden,\n * a complete list of base contracts has to be given.\n */\noverrideSpecifier: Override (LParen overrides+=identifierPath (Comma overrides+=identifierPath)* RParen)?;\n/**\n * The definition of contract, library, interface or free functions.\n * Depending on the context in which the function is defined, further restrictions may apply,\n * e.g. functions in interfaces have to be unimplemented, i.e. may not contain a body block.\n */\nfunctionDefinition\nlocals[\n\tboolean visibilitySet = false,\n\tboolean mutabilitySet = false,\n\tboolean virtualSet = false,\n\tboolean overrideSpecifierSet = false,\n]\n:\n\tFunction (identifier | Fallback | Receive)\n\tLParen (arguments=parameterList)? RParen\n\t(\n\t\t{!$visibilitySet}? visibility {$visibilitySet = true;}\n\t\t| {!$mutabilitySet}? stateMutability {$mutabilitySet = true;}\n\t\t| modifierInvocation\n\t\t| {!$virtualSet}? Virtual {$virtualSet = true;}\n\t\t| {!$overrideSpecifierSet}? overrideSpecifier {$overrideSpecifierSet = true;}\n\t )*\n\t(Returns LParen returnParameters=parameterList RParen)?\n\t(Semicolon | body=block);\n\n/**\n * The definition of a modifier.\n * Note that within the body block of a modifier, the underscore cannot be used as identifier,\n * but is used as placeholder statement for the body of a function to which the modifier is applied.\n */\nmodifierDefinition\nlocals[\n\tboolean virtualSet = false,\n\tboolean overrideSpecifierSet = false\n]\n:\n\tModifier name=identifier\n\t(LParen (arguments=parameterList)? RParen)?\n\t(\n\t\t{!$virtualSet}? Virtual {$virtualSet = true;}\n\t\t| {!$overrideSpecifierSet}? overrideSpecifier {$overrideSpecifierSet = true;}\n\t)*\n\t(Semicolon | body=block);\n\n/**\n * Definition of the special fallback function.\n */\nfallbackFunctionDefinition\nlocals[\n\tboolean visibilitySet = false,\n\tboolean mutabilitySet = false,\n\tboolean virtualSet = false,\n\tboolean overrideSpecifierSet = false,\n\tboolean hasParameters = false\n]\n:\n\tkind=Fallback LParen (parameterList { $hasParameters = true; } )? RParen\n\t(\n\t\t{!$visibilitySet}? External {$visibilitySet = true;}\n\t\t| {!$mutabilitySet}? stateMutability {$mutabilitySet = true;}\n\t\t| modifierInvocation\n\t\t| {!$virtualSet}? Virtual {$virtualSet = true;}\n\t\t| {!$overrideSpecifierSet}? overrideSpecifier {$overrideSpecifierSet = true;}\n\t)*\n\t( {$hasParameters}? Returns LParen returnParameters=parameterList RParen | {!$hasParameters}? )\n\t(Semicolon | body=block);\n\n/**\n * Definition of the special receive function.\n */\nreceiveFunctionDefinition\nlocals[\n\tboolean visibilitySet = false,\n\tboolean mutabilitySet = false,\n\tboolean virtualSet = false,\n\tboolean overrideSpecifierSet = false\n]\n:\n\tkind=Receive LParen RParen\n\t(\n\t\t{!$visibilitySet}? External {$visibilitySet = true;}\n\t\t| {!$mutabilitySet}? Payable {$mutabilitySet = true;}\n\t\t| modifierInvocation\n\t\t| {!$virtualSet}? Virtual {$virtualSet = true;}\n\t\t| {!$overrideSpecifierSet}? overrideSpecifier {$overrideSpecifierSet = true;}\n\t )*\n\t(Semicolon | body=block);\n\n/**\n * Definition of a struct. Can occur at top-level within a source unit or within a contract, library or interface.\n */\nstructDefinition: Struct name=identifier LBrace members=structMember+ RBrace;\n/**\n * The declaration of a named struct member.\n */\nstructMember: type=typeName name=identifier Semicolon;\n/**\n * Definition of an enum. Can occur at top-level within a source unit or within a contract, library or interface.\n */\nenumDefinition: Enum name=identifier LBrace enumValues+=identifier (Comma enumValues+=identifier)* RBrace;\n/**\n * Definition of a user defined value type. Can occur at top-level within a source unit or within a contract, library or interface.\n */\nuserDefinedValueTypeDefinition:\n\tType name=identifier Is elementaryTypeName[true] Semicolon;\n\n/**\n * The declaration of a state variable.\n */\nstateVariableDeclaration\nlocals [boolean constantnessSet = false, boolean visibilitySet = false, boolean overrideSpecifierSet = false, boolean locationSet = false]\n:\n\ttype=typeName\n\t(\n\t\t{!$visibilitySet}? Public {$visibilitySet = true;}\n\t\t| {!$visibilitySet}? Private {$visibilitySet = true;}\n\t\t| {!$visibilitySet}? Internal {$visibilitySet = true;}\n\t\t| {!$constantnessSet}? Constant {$constantnessSet = true;}\n\t\t| {!$overrideSpecifierSet}? overrideSpecifier {$overrideSpecifierSet = true;}\n\t\t| {!$constantnessSet}? Immutable {$constantnessSet = true;}\n\t\t| {!$locationSet}? Transient {$locationSet = true;}\n\t)*\n\tname=identifier\n\t(Assign initialValue=expression)?\n\tSemicolon;\n\n/**\n * The declaration of a constant variable.\n */\nconstantVariableDeclaration\n:\n\ttype=typeName\n\tConstant\n\tname=identifier\n\tAssign initialValue=expression\n\tSemicolon;\n\n/**\n * Parameter of an event.\n */\neventParameter: type=typeName Indexed? name=identifier?;\n/**\n * Definition of an event. Can occur in contracts, libraries or interfaces.\n */\neventDefinition:\n\tEvent name=identifier\n\tLParen (parameters+=eventParameter (Comma parameters+=eventParameter)*)? RParen\n\tAnonymous?\n\tSemicolon;\n\n/**\n * Parameter of an error.\n */\nerrorParameter: type=typeName name=identifier?;\n/**\n * Definition of an error.\n */\nerrorDefinition:\n\tError name=identifier\n\tLParen (parameters+=errorParameter (Comma parameters+=errorParameter)*)? RParen\n\tSemicolon;\n\n/**\n * Operators that users are allowed to implement for some types with `using for`.\n */\nuserDefinableOperator:\n\tBitAnd\n\t| BitNot\n\t| BitOr\n\t| BitXor\n\t| Add\n\t| Div\n\t| Mod\n\t| Mul\n\t| Sub\n\t| Equal\n\t| GreaterThan\n\t| GreaterThanOrEqual\n\t| LessThan\n\t| LessThanOrEqual\n\t| NotEqual;\n\n/**\n * Using directive to attach library functions and free functions to types.\n * Can occur within contracts and libraries and at the file level.\n */\nusingDirective:\n Using (\n identifierPath\n | (LBrace usingAliases (Comma usingAliases)* RBrace)\n ) For (Mul | typeName) Global? Semicolon;\n\nusingAliases: identifierPath (As userDefinableOperator)?;\n\n/**\n * A type name can be an elementary type, a function type, a mapping type, a user-defined type\n * (e.g. a contract or struct) or an array type.\n */\ntypeName: elementaryTypeName[true] | functionTypeName | mappingType | identifierPath | typeName LBrack expression? RBrack;\nelementaryTypeName[boolean allowAddressPayable]: Address | {$allowAddressPayable}? Address Payable | Bool | String | Bytes | SignedIntegerType | UnsignedIntegerType | FixedBytes | Fixed | Ufixed;\nfunctionTypeName\nlocals [boolean visibilitySet = false, boolean mutabilitySet = false]\n:\n\tFunction LParen (arguments=parameterList)? RParen\n\t(\n\t\t{!$visibilitySet}? visibility {$visibilitySet = true;}\n\t\t| {!$mutabilitySet}? stateMutability {$mutabilitySet = true;}\n\t)*\n\t(Returns LParen returnParameters=parameterList RParen)?;\n\n/**\n * The declaration of a single variable.\n */\nvariableDeclaration: type=typeName location=dataLocation? name=identifier;\ndataLocation: Memory | Storage | Calldata;\n\n/**\n * Complex expression.\n * Can be an index access, an index range access, a member access, a function call (with optional function call options),\n * a type conversion, an unary or binary expression, a comparison or assignment, a ternary expression,\n * a new-expression (i.e. a contract creation or the allocation of a dynamic memory array),\n * a tuple, an inline array or a primary expression (i.e. an identifier, literal or type name).\n */\nexpression:\n\texpression LBrack index=expression? RBrack # IndexAccess\n\t| expression LBrack startIndex=expression? Colon endIndex=expression? RBrack # IndexRangeAccess\n\t| expression Period (identifier | Address) # MemberAccess\n\t| expression LBrace (namedArgument (Comma namedArgument)*) RBrace # FunctionCallOptions\n\t| expression callArgumentList # FunctionCall\n\t| Payable callArgumentList # PayableConversion\n\t| Type LParen typeName RParen # MetaType\n\t| (Inc | Dec | Not | BitNot | Delete | Sub) expression # UnaryPrefixOperation\n\t| expression (Inc | Dec) # UnarySuffixOperation\n\t| expression Exp expression # ExpOperation\n\t| expression (Mul | Div | Mod) expression # MulDivModOperation\n\t| expression (Add | Sub) expression # AddSubOperation\n\t| expression (Shl | Sar | Shr) expression # ShiftOperation\n\t| expression BitAnd expression # BitAndOperation\n\t| expression BitXor expression # BitXorOperation\n\t| expression BitOr expression # BitOrOperation\n\t| expression (LessThan | GreaterThan | LessThanOrEqual | GreaterThanOrEqual) expression # OrderComparison\n\t| expression (Equal | NotEqual) expression # EqualityComparison\n\t| expression And expression # AndOperation\n\t| expression Or expression # OrOperation\n\t| expression Conditional expression Colon expression # Conditional\n\t| expression assignOp expression # Assignment\n\t| New typeName # NewExpr\n\t| tupleExpression # Tuple\n\t| inlineArrayExpression # InlineArray\n\t| (\n\t\tidentifier\n\t\t| literal\n\t\t| literalWithSubDenomination\n\t\t| elementaryTypeName[false]\n\t ) # PrimaryExpression\n;\n\n//@doc:inline\nassignOp: Assign | AssignBitOr | AssignBitXor | AssignBitAnd | AssignShl | AssignSar | AssignShr | AssignAdd | AssignSub | AssignMul | AssignDiv | AssignMod;\ntupleExpression: LParen (expression? ( Comma expression?)* ) RParen;\n/**\n * An inline array expression denotes a statically sized array of the common type of the contained expressions.\n */\ninlineArrayExpression: LBrack (expression ( Comma expression)* ) RBrack;\n\n/**\n * Besides regular non-keyword Identifiers, some keywords like 'from' and 'error' can also be used as identifiers.\n */\nidentifier: Identifier | From | Error | Revert | Global | Transient | Layout | At;\n\nliteral: stringLiteral | numberLiteral | booleanLiteral | hexStringLiteral | unicodeStringLiteral;\n\nliteralWithSubDenomination: numberLiteral SubDenomination;\n\nbooleanLiteral: True | False;\n/**\n * A full string literal consists of either one or several consecutive quoted strings.\n */\nstringLiteral: (NonEmptyStringLiteral | EmptyStringLiteral)+;\n/**\n * A full hex string literal that consists of either one or several consecutive hex strings.\n */\nhexStringLiteral: HexString+;\n/**\n * A full unicode string literal that consists of either one or several consecutive unicode strings.\n */\nunicodeStringLiteral: UnicodeStringLiteral+;\n\n/**\n * Number literals can be decimal or hexadecimal numbers with an optional unit.\n */\nnumberLiteral: DecimalNumber | HexNumber;\n\n/**\n * A curly-braced block of statements. Opens its own scope.\n */\nblock:\n\tLBrace ( statement | uncheckedBlock )* RBrace;\n\nuncheckedBlock: Unchecked block;\n\nstatement:\n\tblock\n\t| simpleStatement\n\t| ifStatement\n\t| forStatement\n\t| whileStatement\n\t| doWhileStatement\n\t| continueStatement\n\t| breakStatement\n\t| tryStatement\n\t| returnStatement\n\t| emitStatement\n\t| revertStatement\n\t| assemblyStatement\n;\n\n//@doc:inline\nsimpleStatement: variableDeclarationStatement | expressionStatement;\n/**\n * If statement with optional else part.\n */\nifStatement: If LParen expression RParen statement (Else statement)?;\n/**\n * For statement with optional init, condition and post-loop part.\n */\nforStatement: For LParen (simpleStatement | Semicolon) (expressionStatement | Semicolon) expression? RParen statement;\nwhileStatement: While LParen expression RParen statement;\ndoWhileStatement: Do statement While LParen expression RParen Semicolon;\n/**\n * A continue statement. Only allowed inside for, while or do-while loops.\n */\ncontinueStatement: Continue Semicolon;\n/**\n * A break statement. Only allowed inside for, while or do-while loops.\n */\nbreakStatement: Break Semicolon;\n/**\n * A try statement. The contained expression needs to be an external function call or a contract creation.\n */\ntryStatement: Try expression (Returns LParen returnParameters=parameterList RParen)? block catchClause+;\n/**\n * The catch clause of a try statement.\n */\ncatchClause: Catch (identifier? LParen (arguments=parameterList) RParen)? block;\n\nreturnStatement: Return expression? Semicolon;\n/**\n * An emit statement. The contained expression needs to refer to an event.\n */\nemitStatement: Emit expression callArgumentList Semicolon;\n/**\n * A revert statement. The contained expression needs to refer to an error.\n */\nrevertStatement: Revert expression callArgumentList Semicolon;\n/**\n * An inline assembly block.\n * The contents of an inline assembly block use a separate scanner/lexer, i.e. the set of keywords and\n * allowed identifiers is different inside an inline assembly block.\n */\nassemblyStatement: Assembly AssemblyDialect? assemblyFlags? AssemblyLBrace yulStatement* YulRBrace;\n\n/**\n * Assembly flags.\n * Comma-separated list of double-quoted strings as flags.\n */\nassemblyFlags: AssemblyBlockLParen AssemblyFlagString (AssemblyBlockComma AssemblyFlagString)* AssemblyBlockRParen;\n\n//@doc:inline\nvariableDeclarationList: variableDeclarations+=variableDeclaration (Comma variableDeclarations+=variableDeclaration)*;\n/**\n * A tuple of variable names to be used in variable declarations.\n * May contain empty fields.\n */\nvariableDeclarationTuple:\n\tLParen\n\t\t(Comma* variableDeclarations+=variableDeclaration)\n\t\t(Comma (variableDeclarations+=variableDeclaration)?)*\n\tRParen;\n/**\n * A variable declaration statement.\n * A single variable may be declared without initial value, whereas a tuple of variables can only be\n * declared with initial value.\n */\nvariableDeclarationStatement: ((variableDeclaration (Assign expression)?) | (variableDeclarationTuple Assign expression)) Semicolon;\nexpressionStatement: expression Semicolon;\n\nmappingType: Mapping LParen key=mappingKeyType name=identifier? DoubleArrow value=typeName name=identifier? RParen;\n/**\n * Only elementary types or user defined types are viable as mapping keys.\n */\nmappingKeyType: elementaryTypeName[false] | identifierPath;\n\n/**\n * A Yul statement within an inline assembly block.\n * continue and break statements are only valid within for loops.\n * leave statements are only valid within function bodies.\n */\nyulStatement:\n\tyulBlock\n\t| yulVariableDeclaration\n\t| yulAssignment\n\t| yulFunctionCall\n\t| yulIfStatement\n\t| yulForStatement\n\t| yulSwitchStatement\n\t| YulLeave\n\t| YulBreak\n\t| YulContinue\n\t| yulFunctionDefinition;\n\nyulBlock: YulLBrace yulStatement* YulRBrace;\n\n/**\n * The declaration of one or more Yul variables with optional initial value.\n * If multiple variables are declared, only a function call is a valid initial value.\n */\nyulVariableDeclaration:\n\t(YulLet variables+=YulIdentifier (YulAssign yulExpression)?)\n\t| (YulLet variables+=YulIdentifier (YulComma variables+=YulIdentifier)* (YulAssign yulFunctionCall)?);\n\n/**\n * Any expression can be assigned to a single Yul variable, whereas\n * multi-assignments require a function call on the right-hand side.\n */\nyulAssignment: yulPath YulAssign yulExpression | (yulPath (YulComma yulPath)+) YulAssign yulFunctionCall;\n\nyulIfStatement: YulIf cond=yulExpression body=yulBlock;\n\nyulForStatement: YulFor init=yulBlock cond=yulExpression post=yulBlock body=yulBlock;\n\n//@doc:inline\nyulSwitchCase: YulCase yulLiteral yulBlock;\n/**\n * A Yul switch statement can consist of only a default-case (deprecated) or\n * one or more non-default cases optionally followed by a default-case.\n */\nyulSwitchStatement:\n\tYulSwitch yulExpression\n\t(\n\t\t(yulSwitchCase+ (YulDefault yulBlock)?)\n\t\t| (YulDefault yulBlock)\n\t);\n\nyulFunctionDefinition:\n\tYulFunction YulIdentifier\n\tYulLParen (arguments+=YulIdentifier (YulComma arguments+=YulIdentifier)*)? YulRParen\n\t(YulArrow returnParameters+=YulIdentifier (YulComma returnParameters+=YulIdentifier)*)?\n\tbody=yulBlock;\n\n/**\n * While only identifiers without dots can be declared within inline assembly,\n * paths containing dots can refer to declarations outside the inline assembly block.\n */\nyulPath: YulIdentifier (YulPeriod (YulIdentifier | YulEVMBuiltin))*;\n/**\n * A call to a function with return values can only occur as right-hand side of an assignment or\n * a variable declaration.\n */\nyulFunctionCall: (YulIdentifier | YulEVMBuiltin) YulLParen (yulExpression (YulComma yulExpression)*)? YulRParen;\nyulBoolean: YulTrue | YulFalse;\nyulLiteral: YulDecimalNumber | YulStringLiteral | YulHexNumber | yulBoolean | YulHexStringLiteral;\nyulExpression: yulPath | yulFunctionCall | yulLiteral;\n" }, { "path": "docs/grammar.rst", "content": "****************\nLanguage Grammar\n****************\n\n.. syntax:autogrammar:: SolidityParser.g4\n :root-rule: SolidityParser.sourceUnit\n :undocumented:\n :cc-to-dash:\n\n.. syntax:autogrammar:: SolidityLexer.g4\n :root-rule: SolidityParser.sourceUnit\n :fragments:\n :cc-to-dash:" }, { "path": "docs/index.rst", "content": "Solidity\n========\n\nSolidity is an object-oriented, high-level language for implementing smart contracts.\nSmart contracts are programs that govern the behavior of accounts within the Ethereum state.\n\nSolidity is a `curly-bracket language `_ designed to target the Ethereum Virtual Machine (EVM).\nIt is influenced by C++, Python, and JavaScript.\nYou can find more details about which languages Solidity has been inspired by in the :doc:`language influences ` section.\n\nSolidity is statically typed, supports inheritance, libraries, and complex user-defined types, among other features.\n\nWith Solidity, you can create contracts for uses such as voting, crowdfunding, blind auctions, and multi-signature wallets.\n\nWhen deploying contracts, you should use the latest released version of Solidity.\nApart from exceptional cases, only the latest version receives\n`security fixes `_.\nFurthermore, breaking changes, as well as new features, are introduced regularly.\nWe currently use a 0.y.z version number `to indicate this fast pace of change `_.\n\n.. warning::\n\n Solidity recently released the 0.8.x version that introduced a lot of breaking changes.\n Make sure you read :doc:`the full list <080-breaking-changes>`.\n\nIdeas for improving Solidity or this documentation are always welcome,\nread our :doc:`contributors guide ` for more details.\n\n.. Hint::\n\n You can download this documentation as PDF, HTML or Epub\n by clicking on the versions flyout menu in the bottom-right corner and selecting the preferred download format.\n\n\nGetting Started\n---------------\n\n**1. Understand the Smart Contract Basics**\n\nIf 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:\n\n* :ref:`A simple example smart contract ` written in Solidity.\n* :ref:`Blockchain Basics `.\n* :ref:`The Ethereum Virtual Machine `.\n\n**2. Get to Know Solidity**\n\nOnce you are accustomed to the basics, we recommend you read the :doc:`\"Solidity by Example\" `\nand “Language Description” sections to understand the core concepts of the language.\n\n**3. Install the Solidity Compiler**\n\nThere are various ways to install the Solidity compiler,\nsimply choose your preferred option and follow the steps outlined on the :ref:`installation page `.\n\n.. hint::\n You can try out code examples directly in your browser with the\n `Remix IDE `_.\n Remix is a web browser-based IDE that allows you to write, deploy and administer Solidity smart contracts,\n without the need to install Solidity locally.\n\n.. warning::\n As humans write software, it can have bugs.\n Therefore, you should follow established software development best practices when writing your smart contracts.\n This includes code review, testing, audits, and correctness proofs.\n Smart contract users are sometimes more confident with code than their authors,\n and blockchains and smart contracts have their own unique issues to watch out for,\n so before working on production code, make sure you read the :ref:`security_considerations` section.\n\n**4. Learn More**\n\nIf you want to learn more about building decentralized applications on Ethereum,\nthe `Ethereum Developer Resources `_ can help you with further general documentation around Ethereum,\nand a wide selection of tutorials, tools, and development frameworks.\n\nIf you have any questions, you can try searching for answers or asking on the\n`Ethereum StackExchange `_,\nor our `Gitter channel `_.\n\n.. _translations:\n\nTranslations\n------------\n\nCommunity contributors help translate this documentation into several languages.\nNote that they have varying degrees of completeness and up-to-dateness.\nThe English version stands as a reference.\n\nYou can switch between languages by clicking on the flyout menu in the bottom-right corner\nand selecting the preferred language.\n\n* `Chinese `_\n* `French `_\n* `Indonesian `_\n* `Japanese `_\n* `Korean `_\n* `Persian `_\n* `Russian `_\n* `Spanish `_\n* `Turkish `_\n\n.. note::\n\n We set up a GitHub organization and translation workflow to help streamline the community efforts.\n Please refer to the translation guide in the `solidity-docs org `_\n for information on how to start a new language or contribute to the community translations.\n\nContents\n========\n\n:ref:`Keyword Index `, :ref:`Search Page `\n\n.. toctree::\n :maxdepth: 2\n :caption: Basics\n\n introduction-to-smart-contracts.rst\n solidity-by-example.rst\n installing-solidity.rst\n\n.. toctree::\n :maxdepth: 2\n :caption: Language Description\n\n layout-of-source-files.rst\n structure-of-a-contract.rst\n types.rst\n units-and-global-variables.rst\n control-structures.rst\n contracts.rst\n assembly.rst\n cheatsheet.rst\n grammar.rst\n\n.. toctree::\n :maxdepth: 2\n :caption: Compiler\n\n using-the-compiler.rst\n analysing-compilation-output.rst\n ir-breaking-changes.rst\n\n.. toctree::\n :maxdepth: 2\n :caption: Internals\n\n internals/layout_in_storage.rst\n internals/layout_in_memory.rst\n internals/layout_in_calldata.rst\n internals/variable_cleanup.rst\n internals/source_mappings.rst\n internals/optimizer.rst\n metadata.rst\n abi-spec.rst\n\n.. toctree::\n :maxdepth: 2\n :caption: Advisory content\n\n security-considerations.rst\n bugs.rst\n 050-breaking-changes.rst\n 060-breaking-changes.rst\n 070-breaking-changes.rst\n 080-breaking-changes.rst\n\n.. toctree::\n :maxdepth: 2\n :caption: Additional Material\n\n natspec-format.rst\n smtchecker.rst\n yul.rst\n path-resolution.rst\n\n.. toctree::\n :maxdepth: 2\n :caption: Resources\n\n style-guide.rst\n common-patterns.rst\n resources.rst\n contributing.rst\n language-influences.rst\n brand-guide.rst\n" }, { "path": "docs/installing-solidity.rst", "content": ".. index:: ! installing\n\n.. _installing-solidity:\n\n################################\nInstalling the Solidity Compiler\n################################\n\nVersioning\n==========\n\nSolidity versions follow `Semantic Versioning `_. In\naddition, patch-level releases with major release 0 (i.e. 0.x.y) will not\ncontain breaking changes. That means code that compiles with version 0.x.y\ncan be expected to compile with 0.x.z where z > y.\n\nIn addition to releases, we provide **prereleases** and **nightly development builds** to make it\neasy for developers to try out upcoming features and provide early feedback.\nNote that such builds contain bleeding-edge code from the development branch and are not guaranteed\nto be of the same quality as full releases.\nDespite our best efforts, they might contain undocumented and/or broken changes that will not\nbecome a part of an actual release. They are not meant for production use.\n\nWhen deploying contracts, you should use the latest released version of Solidity. This\nis because breaking changes, as well as new features and bug fixes are introduced regularly.\nWe currently use a 0.x version number `to indicate this fast pace of change `_.\n\nRemix\n=====\n\n*We recommend Remix for small contracts and for quickly learning Solidity.*\n\n`Access Remix online `_, you do not need to install anything.\nIf you want to use it without connection to the Internet, download Remix Desktop from `the releases page `_.\nRemix is also a convenient option for testing nightly builds\nwithout installing multiple Solidity versions.\n\nFurther options on this page detail installing command-line Solidity compiler software\non your computer. Choose a command-line compiler if you are working on a larger contract\nor if you require more compilation options.\n\n.. _solcjs:\n\nnpm / Node.js\n=============\n\nUse ``npm`` for a convenient and portable way to install ``solcjs``, a Solidity compiler. The\n``solcjs`` program has fewer features than the ways to access the compiler described\nfurther down this page. The\n:ref:`commandline-compiler` documentation assumes you are using\nthe full-featured compiler, ``solc``. The usage of ``solcjs`` is documented inside its own\n`repository `_.\n\nNote: The solc-js project is derived from the C++\n``solc`` by using Emscripten, which means that both use the same compiler source code.\n``solc-js`` can be used in JavaScript projects directly (such as Remix).\nPlease refer to the solc-js repository for instructions.\n\n.. code-block:: bash\n\n npm install --global solc\n\n.. note::\n\n The command-line executable is named ``solcjs``.\n\n The command-line options of ``solcjs`` are not compatible with ``solc`` and tools (such as ``geth``)\n expecting the behavior of ``solc`` will not work with ``solcjs``.\n\nDocker\n======\n\nDocker images of Solidity builds are available using the `solc `_ image from the argotorg organization on ghcr.io.\nUse the ``stable`` tag for the latest released version, and ``nightly`` for potentially unstable changes in the ``develop`` branch.\n\nThe Docker image runs the compiler executable so that you can pass all compiler arguments to it.\nFor example, the command below pulls the stable version of the ``solc`` image (if you do not have it already),\nand runs it in a new container, passing the ``--help`` argument.\n\n.. code-block:: bash\n\n docker run ghcr.io/argotorg/solc:stable --help\n\n.. note::\n\n Specific compiler versions are supported as the Docker image tag such as ``ghcr.io/argotorg/solc:0.8.23``.\n We will be passing the ``stable`` tag here instead of specific version tag to ensure that users get\n the latest version by default and avoid the issue of an out-of-date version.\n\nTo use the Docker image to compile Solidity files on the host machine, mount a\nlocal folder for input and output, and specify the contract to compile. For example:\n\n.. code-block:: bash\n\n docker run \\\n --volume \"/tmp/some/local/path/:/sources/\" \\\n ghcr.io/argotorg/solc:stable \\\n /sources/Contract.sol \\\n --abi \\\n --bin \\\n --output-dir /sources/output/\n\nYou can also use the standard JSON interface (which is recommended when using the compiler with tooling).\nWhen using this interface, it is not necessary to mount any directories as long as the JSON input is\nself-contained (i.e. it does not refer to any external files that would have to be\n:ref:`loaded by the import callback `).\n\n.. code-block:: bash\n\n docker run ghcr.io/argotorg/solc:stable --standard-json < input.json > output.json\n\nLinux Packages\n==============\n\nWe provide :ref:`standalone binaries ` of the compiler that should run on most\ndistributions without any additional installation steps.\n\nUbuntu packages for versions up to 0.8.30 are available in the\n`ethereum/ethereum PPA `_.\nHowever, we have discontinued this distribution method and future versions will not be added there.\n\nSome Linux distributions provide their own packages.\nThese packages are not directly maintained by us but usually kept up-to-date by the respective\npackage maintainers.\n\nUnofficial, community-maintained scripts for building and installing the compiler are also\navailable for some distributions:\n\n- Arch Linux / (AUR):\n\n - `solidity `_ (builds from source),\n - `solidity-bin `_ (uses our standalone binaries).\n\n- Nix:\n\n - `solc.nix `_ (builds from source).\n\n.. note::\n\n Please be aware that these scripts are produced and maintained by users and not vetted in any\n way by the distro maintainers.\n Exercise caution when using them.\n\nThere is also a `snap package `_, however, it is **currently unmaintained**.\nIt is installable in all the `supported Linux distros `_. To\ninstall the latest stable version of solc:\n\n.. code-block:: bash\n\n sudo snap install solc\n\nIf you want to help testing the latest development version of Solidity\nwith the most recent changes, please use the following:\n\n.. code-block:: bash\n\n sudo snap install solc --edge\n\n.. note::\n\n The ``solc`` snap uses strict confinement. This is the most secure mode for snap packages\n but it comes with limitations, like accessing only the files in your ``/home`` and ``/media`` directories.\n For more information, go to `Demystifying Snap Confinement `_.\n\n\nmacOS Packages\n==============\n\nWe distribute the Solidity compiler through Homebrew\nas a build-from-source version. Pre-built bottles are\ncurrently not supported.\n\n.. code-block:: bash\n\n brew update\n brew upgrade\n brew tap ethereum/ethereum\n brew install solidity\n\nTo install the most recent 0.4.x / 0.5.x version of Solidity you can also use ``brew install solidity@4``\nand ``brew install solidity@5``, respectively.\n\nIf you need a specific version of Solidity you can install a\nHomebrew formula directly from Github.\n\nView\n`solidity.rb commits on GitHub `_.\n\nCopy the commit hash of the version you want and check it out on your machine.\n\n.. code-block:: bash\n\n git clone https://github.com/ethereum/homebrew-ethereum.git\n cd homebrew-ethereum\n git checkout \n\nInstall it using ``brew``:\n\n.. code-block:: bash\n\n brew unlink solidity\n # eg. Install 0.4.8\n brew install solidity.rb\n\n.. _static-binaries:\n\nStatic Binaries\n===============\n\nWe maintain a repository containing static builds of past and current compiler versions for all\nsupported platforms at `solc-bin`_. This is also the location where you can find the nightly builds.\n\nThe repository is not only a quick and easy way for end users to get binaries ready to be used\nout-of-the-box but it is also meant to be friendly to third-party tools:\n\n- The content is mirrored to https://binaries.soliditylang.org where it can be easily downloaded over\n HTTPS without any authentication, rate limiting or the need to use git.\n- Content is served with correct ``Content-Type`` headers and lenient CORS configuration so that it\n can be directly loaded by tools running in the browser.\n- Binaries do not require installation or unpacking (exception for older Windows builds\n bundled with necessary DLLs).\n- We strive for a high level of backward-compatibility. Files, once added, are not removed or moved\n without providing a symlink/redirect at the old location. They are also never modified\n in place and should always match the original checksum. The only exception would be broken or\n unusable files with the potential to cause more harm than good if left as is.\n- Files are served over both HTTP and HTTPS. As long as you obtain the file list in a secure way\n (via git, HTTPS, IPFS or just have it cached locally) and verify hashes of the binaries\n after downloading them, you do not have to use HTTPS for the binaries themselves.\n\nThe same binaries are in most cases available on the `Solidity release page on GitHub`_. The\ndifference is that we do not generally update old releases on the GitHub release page. This means\nthat we do not rename them if the naming convention changes and we do not add builds for platforms\nthat were not supported at the time of release. This only happens in ``solc-bin``.\n\nThe ``solc-bin`` repository contains several top-level directories, each representing a single platform.\nEach one includes a ``list.json`` file listing the available binaries. For example in\n``emscripten-wasm32/list.json`` you will find the following information about version 0.7.4:\n\n.. code-block:: json\n\n {\n \"path\": \"solc-emscripten-wasm32-v0.7.4+commit.3f05b770.js\",\n \"version\": \"0.7.4\",\n \"build\": \"commit.3f05b770\",\n \"longVersion\": \"0.7.4+commit.3f05b770\",\n \"keccak256\": \"0x300330ecd127756b824aa13e843cb1f43c473cb22eaf3750d5fb9c99279af8c3\",\n \"sha256\": \"0x2b55ed5fec4d9625b6c7b3ab1abd2b7fb7dd2a9c68543bf0323db2c7e2d55af2\",\n \"urls\": [\n \"dweb:/ipfs/QmTLs5MuLEWXQkths41HiACoXDiH8zxyqBHGFDRSzVE5CS\"\n ]\n }\n\nThis means that:\n\n- You can find the binary in the same directory under the name\n `solc-emscripten-wasm32-v0.7.4+commit.3f05b770.js `_.\n Note that the file might be a symlink, and you will need to resolve it yourself if you are not using\n git to download it or your file system does not support symlinks.\n- The binary is also mirrored at https://binaries.soliditylang.org/emscripten-wasm32/solc-emscripten-wasm32-v0.7.4+commit.3f05b770.js.\n In this case git is not necessary and symlinks are resolved transparently, either by serving a copy\n of the file or returning a HTTP redirect.\n- The file is also available on IPFS at `QmTLs5MuLEWXQkths41HiACoXDiH8zxyqBHGFDRSzVE5CS`_.\n Please, be aware that the order of items in the ``urls`` array is not predetermined or guaranteed and users should not rely on it.\n- You can verify the integrity of the binary by comparing its keccak256 hash to\n ``0x300330ecd127756b824aa13e843cb1f43c473cb22eaf3750d5fb9c99279af8c3``. The hash can be computed\n on the command-line using ``keccak256sum`` utility provided by `sha3sum`_ or `keccak256() function\n from ethereumjs-util`_ in JavaScript.\n- You can also verify the integrity of the binary by comparing its sha256 hash to\n ``0x2b55ed5fec4d9625b6c7b3ab1abd2b7fb7dd2a9c68543bf0323db2c7e2d55af2``.\n\n.. warning::\n\n Due to the strong backwards compatibility requirement the repository contains some legacy elements\n but you should avoid using them when writing new tools:\n\n - Use ``emscripten-wasm32/`` (with a fallback to ``emscripten-asmjs/``) instead of ``bin/`` if\n you want the best performance. Until version 0.6.1 we only provided asm.js binaries.\n Starting with 0.6.2 we switched to `WebAssembly builds`_ with much better performance. We have\n rebuilt the older versions for wasm but the original asm.js files remain in ``bin/``.\n The new ones had to be placed in a separate directory to avoid name clashes.\n - Use ``emscripten-asmjs/`` and ``emscripten-wasm32/`` instead of ``bin/`` and ``wasm/`` directories\n if you want to be sure whether you are downloading a wasm or an asm.js binary.\n - Use ``list.json`` instead of ``list.js`` and ``list.txt``. The JSON list format contains all\n the information from the old ones and more.\n\n.. warning::\n - The solc-bin.ethereum.org domain is no longer supported. Going forward,\n we recommend any tools which are still using it as the source of Solidity binaries\n to switch to binaries.soliditylang.org.\n\n.. warning::\n\n The binaries are also available at https://argotorg.github.io/solc-bin/ but this page\n stopped being updated just after the release of version 0.7.2, will not receive any new releases\n or nightly builds for any platform and does not serve the new directory structure, including\n non-emscripten builds.\n\n If you are using it, please switch to https://binaries.soliditylang.org, which is a drop-in\n replacement. This allows us to make changes to the underlying hosting in a transparent way and\n minimize disruption. Unlike the ``argotorg.github.io`` domain, which we do not have any control\n over, ``binaries.soliditylang.org`` is guaranteed to work and maintain the same URL structure\n in the long-term.\n\n.. _IPFS: https://ipfs.io\n.. _solc-bin: https://github.com/argotorg/solc-bin/\n.. _Solidity release page on GitHub: https://github.com/argotorg/solidity/releases\n.. _sha3sum: https://github.com/maandree/sha3sum\n.. _keccak256() function from ethereumjs-util: https://github.com/ethereumjs/ethereumjs-util/blob/master/docs/modules/_hash_.md#const-keccak256\n.. _WebAssembly builds: https://emscripten.org/docs/compiling/WebAssembly.html\n.. _QmTLs5MuLEWXQkths41HiACoXDiH8zxyqBHGFDRSzVE5CS: https://gateway.ipfs.io/ipfs/QmTLs5MuLEWXQkths41HiACoXDiH8zxyqBHGFDRSzVE5CS\n\n.. _building-from-source:\n\nBuilding from Source\n====================\nPrerequisites - All Operating Systems\n-------------------------------------\n\nThe following are dependencies for all builds of Solidity:\n\n.. Note: This has to be kept in sync with `scripts/ci/install_and_check_minimum_requirements.sh`.\n\n+-----------------------------------+-------------------------------------------------------+\n| Software | Notes |\n+===================================+=======================================================+\n| `CMake`_ (version 3.21.3+ on | Cross-platform build file generator. |\n| Windows, 3.13+ otherwise) | |\n+-----------------------------------+-------------------------------------------------------+\n| `Boost`_ (version 1.77+ on | C++ libraries. |\n| Windows, 1.83+ otherwise) | |\n+-----------------------------------+-------------------------------------------------------+\n| `Git`_ | Command-line tool for retrieving source code. |\n+-----------------------------------+-------------------------------------------------------+\n| `z3`_ (version 4.8.16+, Optional) | For use with SMT checker. |\n+-----------------------------------+-------------------------------------------------------+\n\n.. _Git: https://git-scm.com/download\n.. _Boost: https://www.boost.org\n.. _CMake: https://cmake.org/download/\n.. _z3: https://github.com/Z3Prover/z3\n\n.. note::\n Solidity versions prior to 0.5.10 can fail to correctly link against Boost versions 1.70+.\n A possible workaround is to temporarily rename ``/lib/cmake/Boost-1.70.0``\n prior to running the cmake command to configure Solidity.\n\n Starting from 0.5.10 linking against Boost 1.70+ should work without manual intervention.\n\n.. note::\n The default build configuration requires a specific Z3 version (the latest one at the time the\n code was last updated). Changes introduced between Z3 releases often result in slightly different\n (but still valid) results being returned. Our SMT tests do not account for these differences and\n will likely fail with a different version than the one they were written for. This does not mean\n that a build using a different version is faulty. If you pass ``-DSTRICT_Z3_VERSION=OFF`` option\n to CMake, you can build with any version that satisfies the requirement given in the table above.\n If you do this, however, please remember to pass the ``--no-smt`` option to ``scripts/tests.sh``\n to skip the SMT tests.\n\n.. note::\n By default the build is performed in *pedantic mode*, which enables extra warnings and tells the\n compiler to treat all warnings as errors.\n This forces developers to fix warnings as they arise, so they do not accumulate \"to be fixed later\".\n If you are only interested in creating a release build and do not intend to modify the source code\n to deal with such warnings, you can pass ``-DPEDANTIC=OFF`` option to CMake to disable this mode.\n Doing this is not recommended for general use but may be necessary when using a toolchain we are\n not testing with or trying to build an older version with newer tools.\n If you encounter such warnings, please consider\n `reporting them `_.\n\nMinimum Compiler Versions\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe following C++ compilers and their minimum versions can build the Solidity codebase:\n\n.. Note: Minimum versions for GCC and Clang are based on availability in Ubuntu 24.04.\n\n- `GCC `_, version 13.3+\n- `Clang `_, version 18.1.3+\n- `MSVC `_, version 2019+\n\nPrerequisites - macOS\n---------------------\n\nFor macOS builds, ensure that you have the latest version of\n`Xcode installed `_.\nThis contains the `Clang C++ compiler `_, the\n`Xcode IDE `_ and other Apple development\ntools that are required for building C++ applications on OS X.\nIf you are installing Xcode for the first time, or have just installed a new\nversion then you will need to agree to the license before you can do\ncommand-line builds:\n\n.. code-block:: bash\n\n sudo xcodebuild -license accept\n\nOur OS X build script uses `the Homebrew `_\npackage manager for installing external dependencies.\nHere's how to `uninstall Homebrew\n`_,\nif you ever want to start again from scratch.\n\nPrerequisites - Windows\n-----------------------\n\nYou need to install the following dependencies for Windows builds of Solidity:\n\n+-----------------------------------+-------------------------------------------------------+\n| Software | Notes |\n+===================================+=======================================================+\n| `Visual Studio 2019 Build Tools`_ | C++ compiler |\n+-----------------------------------+-------------------------------------------------------+\n| `Visual Studio 2019`_ (Optional) | C++ compiler and dev environment. |\n+-----------------------------------+-------------------------------------------------------+\n| `Boost`_ (version 1.77+) | C++ libraries. |\n+-----------------------------------+-------------------------------------------------------+\n\nIf you already have one IDE and only need the compiler and libraries,\nyou could install Visual Studio 2019 Build Tools.\n\nVisual Studio 2019 provides both IDE and necessary compiler and libraries.\nSo if you have not got an IDE and prefer to develop Solidity, Visual Studio 2019\nmay be a choice for you to get everything setup easily.\n\nHere is the list of components that should be installed\nin Visual Studio 2019 Build Tools or Visual Studio 2019:\n\n* Visual Studio C++ core features\n* VC++ 2019 v141 toolset (x86,x64)\n* Windows Universal CRT SDK\n* Windows 8.1 SDK\n* C++/CLI support\n\n.. _Visual Studio 2019: https://www.visualstudio.com/vs/\n.. _Visual Studio 2019 Build Tools: https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products\n\nWe have a helper script which you can use to install all required external dependencies:\n\n.. code-block:: bat\n\n scripts\\install_deps.ps1\n\nThis will install ``boost`` and ``cmake`` to the ``deps`` subdirectory.\n\nClone the Repository\n--------------------\n\nTo clone the source code, execute the following command:\n\n.. code-block:: bash\n\n git clone --recursive https://github.com/argotorg/solidity.git\n cd solidity\n\nIf you want to help develop Solidity,\nyou should fork Solidity and add your personal fork as a second remote:\n\n.. code-block:: bash\n\n git remote add personal git@github.com:[username]/solidity.git\n\n.. note::\n This method will result in a pre-release build leading to e.g. a flag\n being set in each bytecode produced by such a compiler.\n If you want to re-build a released Solidity compiler, then\n please use the source tarball on the GitHub release page:\n\n https://github.com/argotorg/solidity/releases/download/v0.X.Y/solidity_0.X.Y.tar.gz\n\n (not the \"Source code\" provided by GitHub).\n\nCommand-Line Build\n------------------\n\n**Be sure to install External Dependencies (see above) before build.**\n\nSolidity project uses CMake to configure the build.\nYou might want to install `ccache`_ to speed up repeated builds.\nCMake will pick it up automatically.\nBuilding Solidity is quite similar on Linux, macOS and other Unices:\n\n.. _ccache: https://ccache.dev/\n\n.. code-block:: bash\n\n mkdir build\n cd build\n cmake .. && make\n\nor even easier on Linux and macOS, you can run:\n\n.. code-block:: bash\n\n #note: this will install binaries solc and soltest at usr/local/bin\n ./scripts/build.sh\n\n.. warning::\n\n BSD builds should work, but are untested by the Solidity team.\n\nAnd for Windows:\n\n.. code-block:: bash\n\n mkdir build\n cd build\n cmake -G \"Visual Studio 16 2019\" ..\n\nIn case you want to use the version of boost installed by ``scripts\\install_deps.ps1``, you will\nadditionally need to pass ``-DBoost_ROOT=\"deps/boost\" -DBoost_INCLUDE_DIR=\"deps/boost/include\"`` and ``-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded``\nas arguments to the call to ``cmake``.\n\nThis should result in the creation of **solidity.sln** in that build directory.\nDouble-clicking on that file should result in Visual Studio firing up. We suggest building\n**Release** configuration, but all others work.\n\nAlternatively, you can build for Windows on the command-line, like so:\n\n.. code-block:: bash\n\n cmake --build . --config Release\n\nCMake Options\n=============\n\nIf you are interested what CMake options are available run ``cmake .. -LH``.\n\n.. _smt_solvers_build:\n\nSMT Solvers\n-----------\nSolidity can optionally use SMT solvers, namely ``z3``, ``cvc5`` and ``Eldarica``,\nbut their presence is checked only at runtime, they are not needed for the build to succeed.\n\n.. note::\n\n The emscripten builds require Z3 and will statically link against it instead.\n\nThe Version String in Detail\n============================\n\nThe Solidity version string contains four parts:\n\n- the version number\n- pre-release tag, usually set to ``develop.YYYY.MM.DD``, ``pre.N`` or ``nightly.YYYY.MM.DD``\n- commit in the format of ``commit.GITHASH``\n- platform, which has an arbitrary number of items, containing details about the platform and compiler\n\nIf there are local modifications, the commit will be postfixed with ``.mod``.\n\nThese parts are combined as required by SemVer, where the Solidity pre-release tag equals to the SemVer pre-release\nand the Solidity commit and platform combined make up the SemVer build metadata.\n\nExamples:\n\n- release: ``0.4.8+commit.60cc1668.Emscripten.clang``\n- pre-release: ``0.4.9-pre.3+commit.fb60450bc.Emscripten.clang``\n- nightly build: ``0.4.9-nightly.2017.1.17+commit.6ecb4aa3.Emscripten.clang``\n\nImportant Information About Versioning\n======================================\n\nAfter a release is made, the patch version level is bumped, because we assume that only\npatch level changes follow. When changes are merged, the version should be bumped according\nto SemVer and the severity of the change. Finally, a release is always made with the version\nof the current build, but without the ``prerelease`` specifier.\n\nExample:\n\n1. The 0.4.0 release is made.\n2. Nightly builds and preerelases have a version of 0.4.1 from now on.\n3. Non-breaking changes are introduced --> no change in version.\n4. A breaking change is introduced --> version is bumped to 0.5.0.\n5. The 0.5.0 release is made.\n\nThis behavior works well with the :ref:`version pragma `.\n" }, { "path": "docs/internals/layout_in_calldata.rst", "content": "\n.. index: calldata layout\n\n*******************\nLayout of Call Data\n*******************\n\nThe input data for a function call is assumed to be in the format defined by the :ref:`ABI\nspecification `. Among others, the ABI specification requires arguments to be padded to multiples of 32\nbytes. The internal function calls use a different convention.\n\nArguments for the constructor of a contract are directly appended at the end of the\ncontract's code, also in ABI encoding. The constructor will access them through a hard-coded offset, and\nnot by using the ``codesize`` opcode, since this of course changes when appending\ndata to the code.\n\n" }, { "path": "docs/internals/layout_in_memory.rst", "content": "\n.. index: memory layout\n\n****************\nLayout in Memory\n****************\n\nSolidity reserves four 32-byte slots, with specific byte ranges (inclusive of endpoints) being used as follows:\n\n- ``0x00`` - ``0x3f`` (64 bytes): scratch space for hashing methods\n- ``0x40`` - ``0x5f`` (32 bytes): currently allocated memory size (aka. free memory pointer)\n- ``0x60`` - ``0x7f`` (32 bytes): zero slot\n\nScratch space can be used between statements (i.e. within inline assembly). The zero slot\nis used as initial value for dynamic memory arrays and should never be written to\n(the free memory pointer points to ``0x80`` initially).\n\nSolidity always places new objects at the free memory pointer and\nmemory is never freed (this might change in the future).\n\nElements in memory arrays in Solidity always occupy multiples of 32 bytes (this\nis even true for ``bytes1[]``, but not for ``bytes`` and ``string``).\nMulti-dimensional memory arrays are pointers to memory arrays. The length of a\ndynamic array is stored at the first slot of the array and followed by the array\nelements.\n\n.. warning::\n There are some operations in Solidity that need a temporary memory area\n larger than 64 bytes and therefore will not fit into the scratch space.\n They will be placed where the free memory points to, but given their\n short lifetime, the pointer is not updated. The memory may or may not\n be zeroed out. Because of this, one should not expect the free memory\n to point to zeroed out memory.\n\n While it may seem like a good idea to use ``msize`` to arrive at a\n definitely zeroed out memory area, using such a pointer non-temporarily\n without updating the free memory pointer can have unexpected results.\n\n\nDifferences to Layout in Storage\n================================\n\nAs described above the layout in memory is different from the layout in\n:ref:`storage`. Below there are some examples.\n\nExample for Difference in Arrays\n--------------------------------\n\nThe following array occupies 32 bytes (1 slot) in storage, but 128\nbytes (4 items with 32 bytes each) in memory.\n\n.. code-block:: solidity\n\n uint8[4] a;\n\n\n\nExample for Difference in Struct Layout\n---------------------------------------\n\nThe following struct occupies 96 bytes (3 slots of 32 bytes) in storage,\nbut 128 bytes (4 items with 32 bytes each) in memory.\n\n\n.. code-block:: solidity\n\n struct S {\n uint a;\n uint b;\n uint8 c;\n uint8 d;\n }\n" }, { "path": "docs/internals/layout_in_storage.rst", "content": ".. index:: storage, state variable, mapping, transient storage\n\n**********************************************************\nLayout of State Variables in Storage and Transient Storage\n**********************************************************\n\n.. _storage-inplace-encoding:\n\n.. note::\n The rules described in this section apply for both storage and transient storage data locations.\n The layouts are completely independent and don't interfere with each other's variable locations.\n Thus storage and transient storage state variables can be safely interleaved without any side effects.\n Only value types are supported for transient storage.\n\nState variables of contracts are stored in storage in a compact way such\nthat multiple values sometimes use the same storage slot.\nExcept for dynamically-sized arrays and mappings (see below), data is stored\ncontiguously item after item starting with the first state variable,\nwhich is stored in slot ``0``. For each variable,\na size in bytes is determined according to its type.\nMultiple, contiguous items that need less than 32 bytes are packed into a single\nstorage slot if possible, according to the following rules:\n\n- The first item in a storage slot is stored lower-order aligned.\n- Value types use only as many bytes as are necessary to store them.\n- If a value type does not fit the remaining part of a storage slot, it is stored in the next storage slot.\n- Structs and array data always start a new slot and their items are packed tightly according to these rules.\n- Items following struct or array data always start a new storage slot.\n\nFor contracts that use inheritance, the ordering of state variables is determined by the\nC3-linearized order of contracts starting with the most base-ward contract. If allowed\nby the above rules, state variables from different contracts do share the same storage slot.\n\nThe elements of structs and arrays are stored after each other, just as if they were given\nas individual values.\n\nIf a contract specifies a :ref:`custom storage layout`, the slots assigned\nto static storage variables are shifted according the value defined as the layout base.\nLocations of dynamic arrays and mappings are also indirectly affected by this due to shifting\nof the static slots they are based on.\nThe custom layout is specified in the most derived contract and, following the order explained\nabove, starting from the most base-ward contract's variables, all storage slots are adjusted.\n\nIn the following example, contract ``C`` inherits from contracts ``A`` and ``B`` and also\nspecifies a custom storage base slot.\nThe result is that all storage variable slots of the inheritance tree are adjusted according to\nthe value specified by ``C``.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.29;\n\n struct S {\n int32 x;\n bool y;\n }\n\n contract A {\n uint a;\n uint128 transient b;\n uint constant c = 10;\n uint immutable d = 12;\n }\n\n contract B {\n uint8[] e;\n mapping(uint => S) f;\n uint16 g;\n uint16 h;\n bytes16 transient i;\n S s;\n int8 k;\n }\n\n contract C is A, B layout at 42 {\n bytes21 l;\n uint8[10] m;\n bytes5[8] n;\n bytes5 o;\n }\n\nIn the example, the storage layout starts with the inherited\nstate variable ``a`` stored directly inside the base slot (slot ``42``).\nTransient, constant and immutable variables are stored in separate\nlocations, and thus, ``b``, ``i``, ``c`` and ``d`` have no effect on the storage layout.\nThen we get to the dynamic array ``e`` and mapping ``f``.\nThey both reserve a whole slot whose address will be used to :ref:`calculate`\nthe location where their data is actually stored.\nThe slot cannot be shared with any other variable, because the resulting addresses must be unique.\nThe next two variables, ``g`` and ``h``, need 2 bytes each and can be packed together into\nslot ``45``, at offsets ``0`` and ``2`` respectively.\nSince ``s`` is a struct, its two members are packed contiguously, each taking up 5 bytes.\nEven though they both would still fit in slot ``45``, structs and arrays always start a new slot.\nTherefore, ``s`` is placed in slot ``46`` and the next variable, ``k``, in slot ``47``.\nBase contracts, on the other hand, can share slots with derived ones, so ``l`` does not require an new one.\nThen variable ``m``, which is an array of 10 items, gets into slot ``48`` and takes up 10 bytes.\n``n`` is an array as well, but due to the size of its items, cannot fill its first slot perfectly\nand spills over to the next one.\nFinally, variable ``o`` ends up in slot ``51``, even though it is of the same type as items of ``n``.\nAs explained before, variables after structs and arrays always start a new slot.\n\nPutting it all together, the storage and transient storage layouts of contract ``C`` can be illustrated as follows:\n\n- Storage:\n ::\n\n 42 [aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]\n 43 [eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee]\n 44 [ffffffffffffffffffffffffffffffff]\n 45 [ hhgg]\n 46 [ yxxxx]\n 47 [ lllllllllllllllllllllk]\n 48 [ mmmmmmmmmm]\n 49 [ nnnnnnnnnnnnnnnnnnnnnnnnnnnnnn]\n 50 [ nnnnnnnnnn]\n 51 [ ooooo]\n\n- Transient storage:\n ::\n\n 00 [iiiiiiiiiiiiiiiibbbbbbbbbbbbbbbb]\n\nNote that the storage specifier affects ``A`` and ``B`` only as a part of ``C``'s inheritance hierarchy.\nWhen deployed independently, their storage starts at ``0``:\n\n- Storage layout of ``A``:\n ::\n\n 00 [aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]\n\n- Storage layout of ``B``:\n ::\n\n 00 [eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee]\n 01 [ffffffffffffffffffffffffffffffff]\n 02 [ hhgg]\n 03 [ yxxxx]\n 04 [ k]\n\n.. warning::\n When using elements that are smaller than 32 bytes, your contract's gas usage may be higher.\n This is because the EVM operates on 32 bytes at a time. Therefore, if the element is smaller\n than that, the EVM must use more operations in order to reduce the size of the element from 32\n bytes to the desired size.\n\n It might be beneficial to use reduced-size types if you are dealing with storage values\n because the compiler will pack multiple elements into one storage slot, and thus, combine\n multiple reads or writes into a single operation.\n If you are not reading or writing all the values in a slot at the same time, this can\n have the opposite effect, though: When one value is written to a multi-value storage\n slot, the storage slot has to be read first and then\n combined with the new value such that other data in the same slot is not destroyed.\n\n When dealing with function arguments or memory\n values, there is no inherent benefit because the compiler does not pack these values.\n\n Finally, in order to allow the EVM to optimize for this, ensure that you try to order your\n storage variables and ``struct`` members such that they can be packed tightly. For example,\n declaring your storage variables in the order of ``uint128, uint128, uint256`` instead of\n ``uint128, uint256, uint128``, as the former will only take up two slots of storage whereas the\n latter will take up three.\n\n.. note::\n The layout of state variables in storage is considered to be part of the external interface\n of Solidity due to the fact that storage pointers can be passed to libraries. This means that\n any change to the rules outlined in this section is considered a breaking change\n of the language and due to its critical nature should be considered very carefully before\n being executed. In the event of such a breaking change, we would want to release a\n compatibility mode in which the compiler would generate bytecode supporting the old layout.\n\n\nMappings and Dynamic Arrays\n===========================\n\n.. _storage-hashed-encoding:\n\nDue to their unpredictable size, mappings and dynamically-sized array types cannot be stored\n\"in between\" the state variables preceding and following them.\nInstead, they are considered to occupy only 32 bytes with regards to the\n:ref:`rules above ` and the elements they contain are stored starting at a different\nstorage slot that is computed using a Keccak-256 hash.\n\nAssume the storage location of the mapping or array ends up being a slot ``p``\nafter applying :ref:`the storage layout rules `.\nFor dynamic arrays,\nthis slot stores the number of elements in the array (byte arrays and\nstrings are an exception, see :ref:`below `).\nFor mappings, the slot stays empty, but it is still needed to ensure that even if there are\ntwo mappings next to each other, their content ends up at different storage locations.\n\nArray data is located starting at ``keccak256(p)`` and it is laid out in the same way as\nstatically-sized array data would: One element after the other, potentially sharing\nstorage slots if the elements are not longer than 16 bytes. Dynamic arrays of dynamic arrays apply this\nrule recursively. The location of element ``x[i][j]``, where the type of ``x`` is ``uint24[][]``, is\ncomputed as follows (again, assuming ``x`` itself is stored at slot ``p``):\nThe slot is ``keccak256(keccak256(p) + i) + floor(j / floor(256 / 24))`` and\nthe element can be obtained from the slot data ``v`` using ``(v >> ((j % floor(256 / 24)) * 24)) & type(uint24).max``.\n\nThe value corresponding to a mapping key ``k`` is located at ``keccak256(h(k) . p)``\nwhere ``.`` is concatenation and ``h`` is a function that is applied to the key depending on its type:\n\n- for value types, ``h`` pads the value to 32 bytes in the same way as when storing the value in memory.\n- for strings and byte arrays, ``h(k)`` is just the unpadded data.\n\nIf the mapping value is a\nnon-value type, the computed slot marks the start of the data. If the value is of struct type,\nfor example, you have to add an offset corresponding to the struct member to reach the member.\n\nAs an example, consider the following contract:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.0 <0.9.0;\n\n\n contract C {\n struct S { uint16 a; uint16 b; uint256 c; }\n uint x;\n mapping(uint => mapping(uint => S)) data;\n }\n\nLet us compute the storage location of ``data[4][9].c``.\nThe position of the mapping itself is ``1`` (the variable ``x`` with 32 bytes precedes it).\nThis means ``data[4]`` is stored at ``keccak256(uint256(4) . uint256(1))``. The type of ``data[4]`` is\nagain a mapping and the data for ``data[4][9]`` starts at slot\n``keccak256(uint256(9) . keccak256(uint256(4) . uint256(1)))``.\nThe slot offset of the member ``c`` inside the struct ``S`` is ``1`` because ``a`` and ``b`` are packed\nin a single slot. This means the slot for\n``data[4][9].c`` is ``keccak256(uint256(9) . keccak256(uint256(4) . uint256(1))) + 1``.\nThe type of the value is ``uint256``, so it uses a single slot.\n\n\n.. _bytes-and-string:\n\n``bytes`` and ``string``\n------------------------\n\n``bytes`` and ``string`` are encoded identically.\nIn general, the encoding is similar to ``bytes1[]``, in the sense that there is a slot for the array itself and\na data area that is computed using a ``keccak256`` hash of that slot's position.\nHowever, for short values (shorter than 32 bytes) the array elements are stored together with the length in the same slot.\n\nIn particular: if the data is at most ``31`` bytes long, the elements are stored\nin the higher-order bytes (left aligned) and the lowest-order byte stores the value ``length * 2``.\nFor byte arrays that store data which is ``32`` or more bytes long, the main slot ``p`` stores ``length * 2 + 1`` and the data is\nstored as usual in ``keccak256(p)``. This means that you can distinguish a short array from a long array\nby checking if the lowest bit is set: short (not set) and long (set).\n\n.. note::\n Handling invalidly encoded slots is currently not supported but may be added in the future.\n If you are compiling via IR, reading an invalidly encoded slot results in a ``Panic(0x22)`` error.\n\nJSON Output\n===========\n\n.. _storage-layout-top-level:\n\nThe storage (or transient storage) layout of a contract can be requested via\nthe :ref:`standard JSON interface `. The output is a JSON object containing two keys,\n``storage`` and ``types``. The ``storage`` object is an array where each\nelement has the following form:\n\n\n.. code-block:: json\n\n\n {\n \"astId\": 2,\n \"contract\": \"fileA:A\",\n \"label\": \"x\",\n \"offset\": 0,\n \"slot\": \"0\",\n \"type\": \"t_uint256\"\n }\n\nThe example above is the storage layout of ``contract A { uint x; }`` from source unit ``fileA``\nand\n\n- ``astId`` is the id of the AST node of the state variable's declaration\n- ``contract`` is the name of the contract including its path as prefix\n- ``label`` is the name of the state variable\n- ``offset`` is the offset in bytes within the storage slot according to the encoding\n- ``slot`` is the storage slot where the state variable resides or starts. This\n number may be very large and therefore its JSON value is represented as a\n string.\n- ``type`` is an identifier used as key to the variable's type information (described in the following)\n\nThe given ``type``, in this case ``t_uint256`` represents an element in\n``types``, which has the form:\n\n\n.. code-block:: json\n\n {\n \"encoding\": \"inplace\",\n \"label\": \"uint256\",\n \"numberOfBytes\": \"32\",\n }\n\nwhere\n\n- ``encoding`` how the data is encoded in storage, where the possible values are:\n\n - ``inplace``: data is laid out contiguously in storage (see :ref:`above `).\n - ``mapping``: Keccak-256 hash-based method (see :ref:`above `).\n - ``dynamic_array``: Keccak-256 hash-based method (see :ref:`above `).\n - ``bytes``: single slot or Keccak-256 hash-based depending on the data size (see :ref:`above `).\n\n- ``label`` is the canonical type name.\n- ``numberOfBytes`` is the number of used bytes (as a decimal string).\n Note that if ``numberOfBytes > 32`` this means that more than one slot is used.\n\nSome types have extra information besides the four above. Mappings contain\nits ``key`` and ``value`` types (again referencing an entry in this mapping\nof types), arrays have its ``base`` type, and structs list their ``members`` in\nthe same format as the top-level ``storage`` (see :ref:`above\n`).\n\n.. note::\n The JSON output format of a contract's storage layout is still considered experimental\n and is subject to change in non-breaking releases of Solidity.\n\nThe following example shows a contract and both its storage and transient storage layout,\ncontaining value and reference types, types that are encoded packed, and nested types.\n\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.28;\n contract A {\n struct S {\n uint128 a;\n uint128 b;\n uint[2] staticArray;\n uint[] dynArray;\n }\n\n uint x;\n uint transient y;\n uint w;\n uint transient z;\n\n S s;\n address addr;\n address transient taddr;\n mapping(uint => mapping(address => bool)) map;\n uint[] array;\n string s1;\n bytes b1;\n }\n\nStorage Layout\n--------------\n\n.. code-block:: json\n\n {\n \"storage\": [\n {\n \"astId\": 15,\n \"contract\": \"fileA:A\",\n \"label\": \"x\",\n \"offset\": 0,\n \"slot\": \"0\",\n \"type\": \"t_uint256\"\n },\n {\n \"astId\": 19,\n \"contract\": \"fileA:A\",\n \"label\": \"w\",\n \"offset\": 0,\n \"slot\": \"1\",\n \"type\": \"t_uint256\"\n },\n {\n \"astId\": 24,\n \"contract\": \"fileA:A\",\n \"label\": \"s\",\n \"offset\": 0,\n \"slot\": \"2\",\n \"type\": \"t_struct(S)13_storage\"\n },\n {\n \"astId\": 26,\n \"contract\": \"fileA:A\",\n \"label\": \"addr\",\n \"offset\": 0,\n \"slot\": \"6\",\n \"type\": \"t_address\"\n },\n {\n \"astId\": 34,\n \"contract\": \"fileA:A\",\n \"label\": \"map\",\n \"offset\": 0,\n \"slot\": \"7\",\n \"type\": \"t_mapping(t_uint256,t_mapping(t_address,t_bool))\"\n },\n {\n \"astId\": 37,\n \"contract\": \"fileA:A\",\n \"label\": \"array\",\n \"offset\": 0,\n \"slot\": \"8\",\n \"type\": \"t_array(t_uint256)dyn_storage\"\n },\n {\n \"astId\": 39,\n \"contract\": \"fileA:A\",\n \"label\": \"s1\",\n \"offset\": 0,\n \"slot\": \"9\",\n \"type\": \"t_string_storage\"\n },\n {\n \"astId\": 41,\n \"contract\": \"fileA:A\",\n \"label\": \"b1\",\n \"offset\": 0,\n \"slot\": \"10\",\n \"type\": \"t_bytes_storage\"\n }\n ],\n \"types\": {\n \"t_address\": {\n \"encoding\": \"inplace\",\n \"label\": \"address\",\n \"numberOfBytes\": \"20\"\n },\n \"t_array(t_uint256)2_storage\": {\n \"base\": \"t_uint256\",\n \"encoding\": \"inplace\",\n \"label\": \"uint256[2]\",\n \"numberOfBytes\": \"64\"\n },\n \"t_array(t_uint256)dyn_storage\": {\n \"base\": \"t_uint256\",\n \"encoding\": \"dynamic_array\",\n \"label\": \"uint256[]\",\n \"numberOfBytes\": \"32\"\n },\n \"t_bool\": {\n \"encoding\": \"inplace\",\n \"label\": \"bool\",\n \"numberOfBytes\": \"1\"\n },\n \"t_bytes_storage\": {\n \"encoding\": \"bytes\",\n \"label\": \"bytes\",\n \"numberOfBytes\": \"32\"\n },\n \"t_mapping(t_address,t_bool)\": {\n \"encoding\": \"mapping\",\n \"key\": \"t_address\",\n \"label\": \"mapping(address => bool)\",\n \"numberOfBytes\": \"32\",\n \"value\": \"t_bool\"\n },\n \"t_mapping(t_uint256,t_mapping(t_address,t_bool))\": {\n \"encoding\": \"mapping\",\n \"key\": \"t_uint256\",\n \"label\": \"mapping(uint256 => mapping(address => bool))\",\n \"numberOfBytes\": \"32\",\n \"value\": \"t_mapping(t_address,t_bool)\"\n },\n \"t_string_storage\": {\n \"encoding\": \"bytes\",\n \"label\": \"string\",\n \"numberOfBytes\": \"32\"\n },\n \"t_struct(S)13_storage\": {\n \"encoding\": \"inplace\",\n \"label\": \"struct A.S\",\n \"members\": [\n {\n \"astId\": 3,\n \"contract\": \"fileA:A\",\n \"label\": \"a\",\n \"offset\": 0,\n \"slot\": \"0\",\n \"type\": \"t_uint128\"\n },\n {\n \"astId\": 5,\n \"contract\": \"fileA:A\",\n \"label\": \"b\",\n \"offset\": 16,\n \"slot\": \"0\",\n \"type\": \"t_uint128\"\n },\n {\n \"astId\": 9,\n \"contract\": \"fileA:A\",\n \"label\": \"staticArray\",\n \"offset\": 0,\n \"slot\": \"1\",\n \"type\": \"t_array(t_uint256)2_storage\"\n },\n {\n \"astId\": 12,\n \"contract\": \"fileA:A\",\n \"label\": \"dynArray\",\n \"offset\": 0,\n \"slot\": \"3\",\n \"type\": \"t_array(t_uint256)dyn_storage\"\n }\n ],\n \"numberOfBytes\": \"128\"\n },\n \"t_uint128\": {\n \"encoding\": \"inplace\",\n \"label\": \"uint128\",\n \"numberOfBytes\": \"16\"\n },\n \"t_uint256\": {\n \"encoding\": \"inplace\",\n \"label\": \"uint256\",\n \"numberOfBytes\": \"32\"\n }\n }\n }\n\nTransient Storage Layout\n------------------------\n\n.. code-block:: json\n\n {\n \"storage\": [\n {\n \"astId\": 17,\n \"contract\": \"fileA:A\",\n \"label\": \"y\",\n \"offset\": 0,\n \"slot\": \"0\",\n \"type\": \"t_uint256\"\n },\n {\n \"astId\": 21,\n \"contract\": \"fileA:A\",\n \"label\": \"z\",\n \"offset\": 0,\n \"slot\": \"1\",\n \"type\": \"t_uint256\"\n },\n {\n \"astId\": 28,\n \"contract\": \"fileA:A\",\n \"label\": \"taddr\",\n \"offset\": 0,\n \"slot\": \"2\",\n \"type\": \"t_address\"\n }\n ],\n \"types\": {\n \"t_address\": {\n \"encoding\": \"inplace\",\n \"label\": \"address\",\n \"numberOfBytes\": \"20\"\n },\n \"t_uint256\": {\n \"encoding\": \"inplace\",\n \"label\": \"uint256\",\n \"numberOfBytes\": \"32\"\n }\n }\n }\n" }, { "path": "docs/internals/optimizer.rst", "content": ".. index:: optimizer, optimiser, common subexpression elimination, constant propagation\n.. _optimizer:\n\n*************\nThe Optimizer\n*************\n\nThe Solidity compiler involves optimizations at three different levels (in order of execution):\n\n- Optimizations during code generation based on a direct analysis of Solidity code.\n- Optimizing transformations on the Yul IR code.\n- Optimizations at the opcode level.\n\nThe opcode-based optimizer applies a set of `simplification rules `_\nto opcodes. It also combines equal code sets and removes unused code.\n\nThe Yul-based optimizer is much more powerful, because it can work across function\ncalls. For example, arbitrary jumps are not possible in Yul, so it is\npossible to compute the side-effects of each function. Consider two function calls,\nwhere the first does not modify storage and the second does modify storage.\nIf their arguments and return values do not depend on each other, we can reorder\nthe function calls. Similarly, if a function is\nside-effect free and its result is multiplied by zero, you can remove the function\ncall completely.\n\nThe codegen-based optimizer affects the initial low-level code produced from the Solidity input.\nIn the legacy pipeline, the bytecode is generated immediately and most of the optimizations of this\nkind are implicit and not configurable, the only exception being an optimization which changes the\norder of literals in binary operations.\nThe IR-based pipeline takes a different approach and produces Yul IR closely matching the structure\nof the Solidity code, with nearly all optimizations deferred to the Yul optimizer module.\nIn that case codegen-level optimization is done only in very limited cases which are difficult to\nhandle in Yul IR, but are straightforward with the high-level information from analysis phase at hand.\nAn example of such an optimization is the bypass of checked arithmetic when incrementing the counter\nin certain idiomatic ``for`` loops.\n\nCurrently, the parameter ``--optimize`` activates the opcode-based optimizer for the\ngenerated bytecode and the Yul optimizer for the Yul code generated internally, for example for ABI coder v2.\nOne can use ``solc --ir-optimized --optimize`` to produce an\noptimized Yul IR for a Solidity source. Similarly, one can use ``solc --strict-assembly --optimize``\nfor a stand-alone Yul mode.\n\n.. note::\n Some optimizer steps, such as, for example, the `peephole optimizer `_\n and the :ref:`unchecked loop increment optimizer ` are always\n enabled by default and can only be turned off via the :ref:`Standard JSON `.\n\n.. note::\n An empty optimizer sequence, i.e ``:``, is accepted even without ``--optimize`` in order to fully disable\n the user-supplied portion of the Yul :ref:`optimizer sequence `, as by default,\n even when the optimizer is not turned on, the :ref:`unused pruner ` step will be run.\n\nYou can find more details on both optimizer modules and their optimization steps below.\n\nBenefits of Optimizing Solidity Code\n====================================\n\nOverall, the optimizer tries to simplify complicated expressions, which reduces both code\nsize and execution cost, i.e., it can reduce gas needed for contract deployment as well as for external calls made to the contract.\nIt also specializes or inlines functions. Especially\nfunction inlining is an operation that can cause much bigger code, but it is\noften done because it results in opportunities for more simplifications.\n\n\nDifferences between Optimized and Non-Optimized Code\n====================================================\n\nGenerally, the most visible difference is that constant expressions are evaluated at compile time.\nWhen it comes to the ASM output, one can also notice a reduction of equivalent or duplicate\ncode blocks (compare the output of the flags ``--asm`` and ``--asm --optimize``). However,\nwhen it comes to the Yul/intermediate-representation, there can be significant\ndifferences, for example, functions may be inlined, combined, or rewritten to eliminate\nredundancies, etc. (compare the output between the flags ``--ir`` and\n``--optimize --ir-optimized``).\n\n.. _optimizer-parameter-runs:\n\nOptimizer Parameter Runs\n========================\n\nThe number of runs (``--optimize-runs``) specifies roughly how often each opcode of the\ndeployed code will be executed across the life-time of the contract. This means it is a\ntrade-off parameter between code size (deploy cost) and code execution cost (cost after deployment).\nA \"runs\" parameter of \"1\" will produce short but expensive code. In contrast, a larger \"runs\"\nparameter will produce longer but more gas efficient code. The maximum value of the parameter\nis ``2**32-1``.\n\n.. note::\n\n A common misconception is that this parameter specifies the number of iterations of the optimizer.\n This is not true: The optimizer will always run as many times as it can still improve the code.\n\nOpcode-Based Optimizer Module\n=============================\n\nThe opcode-based optimizer module operates on assembly code. It splits the\nsequence of instructions into basic blocks at ``JUMPs`` and ``JUMPDESTs``.\nInside these blocks, the optimizer analyzes the instructions and records every modification to the stack,\nmemory, or storage as an expression which consists of an instruction and\na list of arguments which are pointers to other expressions.\n\nAdditionally, the opcode-based optimizer\nuses a component called \"CommonSubexpressionEliminator\" that, amongst other\ntasks, finds expressions that are always equal (on every input) and combines\nthem into an expression class. It first tries to find each new\nexpression in a list of already known expressions. If no such matches are found,\nit simplifies the expression according to rules like\n``constant + constant = sum_of_constants`` or ``X * 1 = X``. Since this is\na recursive process, we can also apply the latter rule if the second factor\nis a more complex expression which we know always evaluates to one.\n\nCertain optimizer steps symbolically track the storage and memory locations. For example, this\ninformation is used to compute Keccak-256 hashes that can be evaluated during compile time. Consider\nthe sequence:\n\n.. code-block:: none\n\n PUSH 32\n PUSH 0\n CALLDATALOAD\n PUSH 100\n DUP2\n MSTORE\n KECCAK256\n\nor the equivalent Yul\n\n.. code-block:: yul\n\n let x := calldataload(0)\n mstore(x, 100)\n let value := keccak256(x, 32)\n\nIn this case, the optimizer tracks the value at a memory location ``calldataload(0)`` and then\nrealizes that the Keccak-256 hash can be evaluated at compile time. This only works if there is no\nother instruction that modifies memory between the ``mstore`` and ``keccak256``. So if there is an\ninstruction that writes to memory (or storage), then we need to erase the knowledge of the current\nmemory (or storage). There is, however, an exception to this erasing, when we can easily see that\nthe instruction doesn't write to a certain location.\n\nFor example,\n\n.. code-block:: yul\n\n let x := calldataload(0)\n mstore(x, 100)\n // Current knowledge memory location x -> 100\n let y := add(x, 32)\n // Does not clear the knowledge that x -> 100, since y does not write to [x, x + 32)\n mstore(y, 200)\n // This Keccak-256 can now be evaluated\n let value := keccak256(x, 32)\n\nTherefore, modifications to storage and memory locations, of say location ``l``, must erase\nknowledge about storage or memory locations which may be equal to ``l``. More specifically, for\nstorage, the optimizer has to erase all knowledge of symbolic locations, that may be equal to ``l``\nand for memory, the optimizer has to erase all knowledge of symbolic locations that may not be at\nleast 32 bytes away. If ``m`` denotes an arbitrary location, then this decision on erasure is done\nby computing the value ``sub(l, m)``. For storage, if this value evaluates to a literal that is\nnon-zero, then the knowledge about ``m`` will be kept. For memory, if the value evaluates to a\nliteral that is between ``32`` and ``2**256 - 32``, then the knowledge about ``m`` will be kept. In\nall other cases, the knowledge about ``m`` will be erased.\n\nAfter this process, we know which expressions have to be on the stack at\nthe end, and have a list of modifications to memory and storage. This information\nis stored together with the basic blocks and is used to link them. Furthermore,\nknowledge about the stack, storage and memory configuration is forwarded to\nthe next block(s).\n\nIf we know the targets of all ``JUMP`` and ``JUMPI`` instructions,\nwe can build a complete control flow graph of the program. If there is only\none target we do not know (this can happen as in principle, jump targets can\nbe computed from inputs), we have to erase all knowledge about the input state\nof a block as it can be the target of the unknown ``JUMP``. If the opcode-based\noptimizer module finds a ``JUMPI`` whose condition evaluates to a constant, it transforms it\nto an unconditional jump.\n\nAs the last step, the code in each block is re-generated. The optimizer creates\na dependency graph from the expressions on the stack at the end of the block,\nand it drops every operation that is not part of this graph. It generates code\nthat applies the modifications to memory and storage in the order they were\nmade in the original code (dropping modifications which were found not to be\nneeded). Finally, it generates all values that are required to be on the\nstack in the correct place.\n\nThese steps are applied to each basic block and the newly generated code\nis used as replacement if it is smaller. If a basic block is split at a\n``JUMPI`` and during the analysis, the condition evaluates to a constant,\nthe ``JUMPI`` is replaced based on the value of the constant. Thus code like\n\n.. code-block:: solidity\n\n uint x = 7;\n data[7] = 9;\n if (data[x] != x + 2) // this condition is never true\n return 2;\n else\n return 1;\n\nsimplifies to this:\n\n.. code-block:: solidity\n\n data[7] = 9;\n return 1;\n\nSimple Inlining\n---------------\n\nSince Solidity version 0.8.2, there is another optimizer step that replaces certain\njumps to blocks containing \"simple\" instructions ending with a \"jump\" by a copy of these instructions.\nThis corresponds to inlining of simple, small Solidity or Yul functions. In particular, the sequence\n``PUSHTAG(tag) JUMP`` may be replaced, whenever the ``JUMP`` is marked as jump \"into\" a\nfunction and behind ``tag`` there is a basic block (as described above for the\n\"CommonSubexpressionEliminator\") that ends in another ``JUMP`` which is marked as a jump\n\"out of\" a function.\n\nIn particular, consider the following prototypical example of assembly generated for a\ncall to an internal Solidity function:\n\n.. code-block:: text\n\n tag_return\n tag_f\n jump // in\n tag_return:\n ...opcodes after call to f...\n\n tag_f:\n ...body of function f...\n jump // out\n\nAs long as the body of the function is a continuous basic block, the \"Inliner\" can replace ``tag_f jump`` by\nthe block at ``tag_f`` resulting in:\n\n.. code-block:: text\n\n tag_return\n ...body of function f...\n jump\n tag_return:\n ...opcodes after call to f...\n\n tag_f:\n ...body of function f...\n jump // out\n\nNow ideally, the other optimizer steps described above will result in the return tag push being moved\ntowards the remaining jump resulting in:\n\n.. code-block:: text\n\n ...body of function f...\n tag_return\n jump\n tag_return:\n ...opcodes after call to f...\n\n tag_f:\n ...body of function f...\n jump // out\n\nIn this situation the \"PeepholeOptimizer\" will remove the return jump. Ideally, all of this can be done\nfor all references to ``tag_f`` leaving it unused, s.t. it can be removed, yielding:\n\n.. code-block:: text\n\n ...body of function f...\n ...opcodes after call to f...\n\nSo the call to function ``f`` is inlined and the original definition of ``f`` can be removed.\n\nInlining like this is attempted, whenever a heuristics suggests that inlining is cheaper over the lifetime of a\ncontract than not inlining. This heuristics depends on the size of the function body, the\nnumber of other references to its tag (approximating the number of calls to the function) and\nthe expected number of executions of the contract (the global optimizer parameter \"runs\").\n\n\nYul-Based Optimizer Module\n==========================\n\nThe Yul-based optimizer consists of several stages and components that all transform\nthe AST in a semantically equivalent way. The goal is to end up either with code\nthat is shorter or at least only marginally longer but will allow further\noptimization steps.\n\n.. warning::\n\n Since the optimizer is under heavy development, the information here might be outdated.\n If you rely on a certain functionality, please reach out to the team directly.\n\nThe optimizer currently follows a purely greedy strategy and does not do any\nbacktracking.\n\nAll components of the Yul-based optimizer module are explained below.\nThe following transformation steps are the main components:\n\n- SSATransform\n- CommonSubexpressionEliminator\n- ExpressionSimplifier\n- UnusedAssignEliminator\n- FullInliner\n\n.. _optimizer-steps:\n\nOptimizer Steps\n---------------\n\nThis is a list of all steps the Yul-based optimizer sorted alphabetically. You can find more information\non the individual steps and their sequence below.\n\n============ ===============================\nAbbreviation Full name\n============ ===============================\n``f`` :ref:`block-flattener`\n``l`` :ref:`circular-references-pruner`\n``c`` :ref:`common-subexpression-eliminator`\n``C`` :ref:`conditional-simplifier`\n``U`` :ref:`conditional-unsimplifier`\n``n`` :ref:`control-flow-simplifier`\n``D`` :ref:`dead-code-eliminator`\n``E`` :ref:`equal-store-eliminator`\n``v`` :ref:`equivalent-function-combiner`\n``e`` :ref:`expression-inliner`\n``j`` :ref:`expression-joiner`\n``s`` :ref:`expression-simplifier`\n``x`` :ref:`expression-splitter`\n``I`` :ref:`for-loop-condition-into-body`\n``O`` :ref:`for-loop-condition-out-of-body`\n``o`` :ref:`for-loop-init-rewriter`\n``i`` :ref:`full-inliner`\n``g`` :ref:`function-grouper`\n``h`` :ref:`function-hoister`\n``F`` :ref:`function-specializer`\n``T`` :ref:`literal-rematerialiser`\n``L`` :ref:`load-resolver`\n``M`` :ref:`loop-invariant-code-motion`\n``m`` :ref:`rematerialiser`\n``V`` :ref:`ssa-reverser`\n``a`` :ref:`ssa-transform`\n``t`` :ref:`structural-simplifier`\n``r`` :ref:`unused-assign-eliminator`\n``p`` :ref:`unused-function-parameter-pruner`\n``S`` :ref:`unused-store-eliminator`\n``u`` :ref:`unused-pruner`\n``d`` :ref:`var-decl-initializer`\n============ ===============================\n\nSome steps depend on properties ensured by ``BlockFlattener``, ``FunctionGrouper``, ``ForLoopInitRewriter``.\nFor this reason the Yul optimizer always applies them before applying any steps supplied by the user.\n\n.. _selecting-optimizations:\n\nSelecting Optimizations\n-----------------------\n\nBy default the optimizer applies its predefined sequence of optimization steps to the generated assembly.\nYou can override this sequence and supply your own using the ``--yul-optimizations`` option:\n\n.. code-block:: bash\n\n solc --optimize --ir-optimized --yul-optimizations 'dhfoD[xarrscLMcCTU]uljmul:fDnTOcmu'\n\nThe order of steps is significant and affects the quality of the output.\nMoreover, applying a step may uncover new optimization opportunities for others that were already applied,\nso repeating steps is often beneficial.\n\nThe sequence inside ``[...]`` will be applied multiple times in a loop until the Yul code\nremains unchanged or until the maximum number of rounds (currently 12) has been reached.\nBrackets (``[]``) may be used multiple times in a sequence, but can not be nested.\n\nAn important thing to note, is that there are some hardcoded steps that are always run before and after the\nuser-supplied sequence, or the default sequence if one was not supplied by the user.\n\nThe cleanup sequence delimiter ``:`` is optional, and is used to supply a custom cleanup sequence\nin order to replace the default one. If omitted, the optimizer will simply apply the default cleanup\nsequence. In addition, the delimiter may be placed at the beginning of the user-supplied sequence,\nwhich will result in the optimization sequence being empty, whereas conversely, if placed at the end of\nthe sequence, will be treated as an empty cleanup sequence.\n\nPreprocessing\n-------------\n\nThe preprocessing components perform transformations to get the program\ninto a certain normal form that is easier to work with. This normal\nform is kept during the rest of the optimization process.\n\n.. _disambiguator:\n\nDisambiguator\n^^^^^^^^^^^^^\n\nThe disambiguator takes an AST and returns a fresh copy where all identifiers have\nunique names in the input AST. This is a prerequisite for all other optimizer stages.\nOne of the benefits is that identifier lookup does not need to take scopes into account\nwhich simplifies the analysis needed for other steps.\n\nAll subsequent stages have the property that all names stay unique. This means if\na new identifier needs to be introduced, a new unique name is generated.\n\n.. _function-hoister:\n\nFunctionHoister\n^^^^^^^^^^^^^^^\n\nThe function hoister moves all function definitions to the end of the topmost block. This is\na semantically equivalent transformation as long as it is performed after the\ndisambiguation stage. The reason is that moving a definition to a higher-level block cannot decrease\nits visibility and it is impossible to reference variables defined in a different function.\n\nThe benefit of this stage is that function definitions can be looked up more easily\nand functions can be optimized in isolation without having to traverse the AST completely.\n\n.. _function-grouper:\n\nFunctionGrouper\n^^^^^^^^^^^^^^^\n\nThe function grouper has to be applied after the Disambiguator and the FunctionHoister.\nIts effect is that all topmost elements that are not function definitions are moved\ninto a single block which is the first statement of the root block.\n\nAfter this step, a program has the following normal form:\n\n.. code-block:: text\n\n { I F... }\n\nWhere ``I`` is a (potentially empty) block that does not contain any function definitions (not even recursively)\nand ``F`` is a list of function definitions such that no function contains a function definition.\n\nThe benefit of this stage is that we always know where the list of functions begins.\n\n.. _for-loop-condition-into-body:\n\nForLoopConditionIntoBody\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis transformation moves the loop-iteration condition of a ``for`` loop into loop body.\nWe need this transformation because :ref:`expression-splitter` will not\napply to iteration condition expressions (the ``C`` in the following example).\n\n.. code-block:: text\n\n for { Init... } C { Post... } {\n Body...\n }\n\nis transformed to\n\n.. code-block:: text\n\n for { Init... } 1 { Post... } {\n if iszero(C) { break }\n Body...\n }\n\nThis transformation can also be useful when paired with LoopInvariantCodeMotion, since\ninvariants in the loop-invariant conditions can then be taken outside the loop.\n\n.. _for-loop-init-rewriter:\n\nForLoopInitRewriter\n^^^^^^^^^^^^^^^^^^^\n\nThis transformation moves the initialization part of a ``for`` loop to before\nthe loop:\n\n.. code-block:: text\n\n for { Init... } C { Post... } {\n Body...\n }\n\nis transformed to\n\n.. code-block:: text\n\n Init...\n for {} C { Post... } {\n Body...\n }\n\nThis eases the rest of the optimization process because we can ignore\nthe complicated scoping rules of the ``for`` loop initialization block.\n\n.. _var-decl-initializer:\n\nVarDeclInitializer\n^^^^^^^^^^^^^^^^^^\nThis step rewrites variable declarations so that all of them are initialized.\nDeclarations like ``let x, y`` are split into multiple declaration statements.\n\nOnly supports initializing with the zero literal for now.\n\nPseudo-SSA Transformation\n-------------------------\n\nThe purpose of this components is to get the program into a longer form,\nso that other components can more easily work with it. The final representation\nwill be similar to a static-single-assignment (SSA) form, with the difference\nthat it does not make use of explicit \"phi\" functions which combines the values\nfrom different branches of control flow because such a feature does not exist\nin the Yul language. Instead, when control flow merges, if a variable is re-assigned\nin one of the branches, a new SSA variable is declared to hold its current value,\nso that the following expressions still only need to reference SSA variables.\n\nAn example transformation is the following:\n\n.. code-block:: yul\n\n {\n let a := calldataload(0)\n let b := calldataload(0x20)\n if gt(a, 0) {\n b := mul(b, 0x20)\n }\n a := add(a, 1)\n sstore(a, add(b, 0x20))\n }\n\n\nWhen all the following transformation steps are applied, the program will look\nas follows:\n\n.. code-block:: yul\n\n {\n let _1 := 0\n let a_9 := calldataload(_1)\n let a := a_9\n let _2 := 0x20\n let b_10 := calldataload(_2)\n let b := b_10\n let _3 := 0\n let _4 := gt(a_9, _3)\n if _4\n {\n let _5 := 0x20\n let b_11 := mul(b_10, _5)\n b := b_11\n }\n let b_12 := b\n let _6 := 1\n let a_13 := add(a_9, _6)\n let _7 := 0x20\n let _8 := add(b_12, _7)\n sstore(a_13, _8)\n }\n\nNote that the only variable that is re-assigned in this snippet is ``b``.\nThis re-assignment cannot be avoided because ``b`` has different values\ndepending on the control flow. All other variables never change their\nvalue once they are defined. The advantage of this property is that\nvariables can be freely moved around and references to them\ncan be exchanged by their initial value (and vice-versa),\nas long as these values are still valid in the new context.\n\nOf course, the code here is far from being optimized. To the contrary, it is much\nlonger. The hope is that this code will be easier to work with and furthermore,\nthere are optimizer steps that undo these changes and make the code more\ncompact again at the end.\n\n.. _expression-splitter:\n\nExpressionSplitter\n^^^^^^^^^^^^^^^^^^\n\nThe expression splitter turns expressions like ``add(mload(0x123), mul(mload(0x456), 0x20))``\ninto a sequence of declarations of unique variables that are assigned sub-expressions\nof that expression so that each function call has only variables\nas arguments.\n\nThe above would be transformed into\n\n.. code-block:: yul\n\n {\n let _1 := 0x20\n let _2 := 0x456\n let _3 := mload(_2)\n let _4 := mul(_3, _1)\n let _5 := 0x123\n let _6 := mload(_5)\n let z := add(_6, _4)\n }\n\nNote that this transformation does not change the order of opcodes or function calls.\n\nIt is not applied to loop iteration-condition, because the loop control flow does not allow\nthis \"outlining\" of the inner expressions in all cases. We can sidestep this limitation by applying\n:ref:`for-loop-condition-into-body` to move the iteration condition into loop body.\n\nThe final program should be in an *expression-split form*, where (with the exception of loop conditions)\nfunction calls cannot appear nested inside expressions\nand all function call arguments have to be variables.\n\nThe benefits of this form are that it is much easier to re-order the sequence of opcodes\nand it is also easier to perform function call inlining. Furthermore, it is simpler\nto replace individual parts of expressions or re-organize the \"expression tree\".\nThe drawback is that such code is much harder to read for humans.\n\n.. _ssa-transform:\n\nSSATransform\n^^^^^^^^^^^^\n\nThis stage tries to replace repeated assignments to\nexisting variables by declarations of new variables as much as\npossible.\nThe reassignments are still there, but all references to the\nreassigned variables are replaced by the newly declared variables.\n\nExample:\n\n.. code-block:: yul\n\n {\n let a := 1\n mstore(a, 2)\n a := 3\n }\n\nis transformed to\n\n.. code-block:: yul\n\n {\n let a_1 := 1\n let a := a_1\n mstore(a_1, 2)\n let a_3 := 3\n a := a_3\n }\n\nExact semantics:\n\nFor any variable ``a`` that is assigned to somewhere in the code\n(variables that are declared with value and never re-assigned\nare not modified) perform the following transforms:\n\n- replace ``let a := v`` by ``let a_i := v let a := a_i``\n- replace ``a := v`` by ``let a_i := v a := a_i`` where ``i`` is a number such that ``a_i`` is yet unused.\n\nFurthermore, always record the current value of ``i`` used for ``a`` and replace each\nreference to ``a`` by ``a_i``.\nThe current value mapping is cleared for a variable ``a`` at the end of each block\nin which it was assigned to and at the end of the ``for`` loop init block if it is assigned\ninside the ``for`` loop body or post block.\nIf a variable's value is cleared according to the rule above and the variable is declared outside\nthe block, a new SSA variable will be created at the location where control flow joins,\nthis includes the beginning of loop post/body block and the location right after\n``if``/``switch``/``for``/block statement.\n\nAfter this stage, the UnusedAssignEliminator is recommended to remove the unnecessary\nintermediate assignments.\n\nThis stage provides best results if the ExpressionSplitter and the CommonSubexpressionEliminator\nare run right before it, because then it does not generate excessive amounts of variables.\nOn the other hand, the CommonSubexpressionEliminator could be more efficient if run after the\nSSA transform.\n\n.. _unused-assign-eliminator:\n\nUnusedAssignEliminator\n^^^^^^^^^^^^^^^^^^^^^^\n\nThe SSA transform always generates an assignment of the form ``a := a_i``, even though\nthese might be unnecessary in many cases, like the following example:\n\n.. code-block:: yul\n\n {\n let a := 1\n a := mload(a)\n a := sload(a)\n sstore(a, 1)\n }\n\nThe SSA transform converts this snippet to the following:\n\n.. code-block:: yul\n\n {\n let a_1 := 1\n let a := a_1\n let a_2 := mload(a_1)\n a := a_2\n let a_3 := sload(a_2)\n a := a_3\n sstore(a_3, 1)\n }\n\nThe UnusedAssignEliminator removes all the three assignments to ``a``, because\nthe value of ``a`` is not used and thus turn this\nsnippet into strict SSA form:\n\n.. code-block:: yul\n\n {\n let a_1 := 1\n let a_2 := mload(a_1)\n let a_3 := sload(a_2)\n sstore(a_3, 1)\n }\n\nOf course the intricate parts of determining whether an assignment is unused or not\nare connected to joining control flow.\n\nThe component works as follows in detail:\n\nThe AST is traversed twice: in an information gathering step and in the\nactual removal step. During information gathering, we maintain a\nmapping from assignment statements to the three states\n\"unused\", \"undecided\" and \"used\" which signifies whether the assigned\nvalue will be used later by a reference to the variable.\n\nWhen an assignment is visited, it is added to the mapping in the \"undecided\" state\n(see remark about ``for`` loops below) and every other assignment to the same variable\nthat is still in the \"undecided\" state is changed to \"unused\".\nWhen a variable is referenced, the state of any assignment to that variable still\nin the \"undecided\" state is changed to \"used\".\n\nAt points where control flow splits, a copy\nof the mapping is handed over to each branch. At points where control flow\njoins, the two mappings coming from the two branches are combined in the following way:\nStatements that are only in one mapping or have the same state are used unchanged.\nConflicting values are resolved in the following way:\n\n- \"unused\", \"undecided\" -> \"undecided\"\n- \"unused\", \"used\" -> \"used\"\n- \"undecided\", \"used\" -> \"used\"\n\nFor ``for`` loops, the condition, body and post-part are visited twice, taking\nthe joining control-flow at the condition into account.\nIn other words, we create three control flow paths: Zero runs of the loop,\none run and two runs and then combine them at the end.\n\nSimulating a third run or even more is unnecessary, which can be seen as follows:\n\nA state of an assignment at the beginning of the iteration will deterministically\nresult in a state of that assignment at the end of the iteration. Let this\nstate mapping function be called ``f``. The combination of the three different\nstates ``unused``, ``undecided`` and ``used`` as explained above is the ``max``\noperation where ``unused = 0``, ``undecided = 1`` and ``used = 2``.\n\nThe proper way would be to compute\n\n.. code-block:: none\n\n max(s, f(s), f(f(s)), f(f(f(s))), ...)\n\nas state after the loop. Since ``f`` just has a range of three different values,\niterating it has to reach a cycle after at most three iterations,\nand thus ``f(f(f(s)))`` has to equal one of ``s``, ``f(s)``, or ``f(f(s))``\nand thus\n\n.. code-block:: none\n\n max(s, f(s), f(f(s))) = max(s, f(s), f(f(s)), f(f(f(s))), ...)\n\nIn summary, running the loop at most twice is enough because there are only three\ndifferent states.\n\nFor ``switch`` statements that have a default case, there is no control-flow\npart that skips the ``switch``.\n\nWhen a variable goes out of scope, all statements still in the \"undecided\"\nstate are changed to \"unused\", unless the variable is the return\nparameter of a function - there, the state changes to \"used\".\n\nIn the second traversal, all assignments that are in the \"unused\" state are removed.\n\nThis step is usually run right after the SSA transform to complete\nthe generation of the pseudo-SSA.\n\nTools\n-----\n\nMovability\n^^^^^^^^^^\n\nMovability is a property of an expression. It roughly means that the expression\nis side-effect free and its evaluation only depends on the values of variables\nand the call-constant state of the environment. Most expressions are movable.\nThe following parts make an expression non-movable:\n\n- function calls (might be relaxed in the future if all statements in the function are movable)\n- opcodes that (can) have side-effects (like ``call`` or ``selfdestruct``)\n- opcodes that read or write memory, storage or external state information\n- opcodes that depend on the current PC, memory size or returndata size\n\nDataflowAnalyzer\n^^^^^^^^^^^^^^^^\n\nThe DataflowAnalyzer is not an optimizer step itself but is used as a tool\nby other components. While traversing the AST, it tracks the current value of\neach variable, as long as that value is a movable expression.\nIt records the variables that are part of the expression\nthat is currently assigned to each other variable. Upon each assignment to\na variable ``a``, the current stored value of ``a`` is updated and\nall stored values of all variables ``b`` are cleared whenever ``a`` is part\nof the currently stored expression for ``b``.\n\nAt control-flow joins, knowledge about variables is cleared if they have or would be assigned\nin any of the control-flow paths. For instance, upon entering a\n``for`` loop, all variables are cleared that will be assigned during the\nbody or the post block.\n\nExpression-Scale Simplifications\n--------------------------------\n\nThese simplification passes change expressions and replace them by equivalent\nand hopefully simpler expressions.\n\n.. _common-subexpression-eliminator:\n\nCommonSubexpressionEliminator\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis step uses the DataflowAnalyzer and replaces subexpressions that\nsyntactically match the current value of a variable by a reference to\nthat variable. This is an equivalence transform because such subexpressions have\nto be movable.\n\nAll subexpressions that are identifiers themselves are replaced by their\ncurrent value if the value is an identifier.\n\nThe combination of the two rules above allow to compute a local value\nnumbering, which means that if two variables have the same\nvalue, one of them will always be unused. The UnusedPruner or the\nUnusedAssignEliminator will then be able to fully eliminate such\nvariables.\n\nThis step is especially efficient if the ExpressionSplitter is run\nbefore. If the code is in pseudo-SSA form,\nthe values of variables are available for a longer time and thus we\nhave a higher chance of expressions to be replaceable.\n\nThe ExpressionSimplifier will be able to perform better replacements\nif the CommonSubexpressionEliminator was run right before it.\n\n.. _expression-simplifier:\n\nExpressionSimplifier\n^^^^^^^^^^^^^^^^^^^^\n\nThe ExpressionSimplifier uses the DataflowAnalyzer and makes use\nof a list of equivalence transforms on expressions like ``X + 0 -> X``\nto simplify the code.\n\nIt tries to match patterns like ``X + 0`` on each subexpression.\nDuring the matching procedure, it resolves variables to their currently\nassigned expressions to be able to match more deeply nested patterns\neven when the code is in pseudo-SSA form.\n\nSome of the patterns like ``X - X -> 0`` can only be applied as long\nas the expression ``X`` is movable, because otherwise it would remove its potential side-effects.\nSince variable references are always movable, even if their current\nvalue might not be, the ExpressionSimplifier is again more powerful\nin split or pseudo-SSA form.\n\n.. _literal-rematerialiser:\n\nLiteralRematerialiser\n^^^^^^^^^^^^^^^^^^^^^\n\nTo be documented.\n\n.. _load-resolver:\n\nLoadResolver\n^^^^^^^^^^^^\n\nOptimisation stage that replaces expressions of type ``sload(x)`` and ``mload(x)`` by the value\ncurrently stored in storage resp. memory, if known.\n\nWorks best if the code is in SSA form.\n\nPrerequisites: Disambiguator, ForLoopInitRewriter.\n\nStatement-Scale Simplifications\n-------------------------------\n\n.. _circular-references-pruner:\n\nCircularReferencesPruner\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis stage removes functions that call each other but are\nneither externally referenced nor referenced from the outermost context.\n\n.. _conditional-simplifier:\n\nConditionalSimplifier\n^^^^^^^^^^^^^^^^^^^^^\n\nThe ConditionalSimplifier inserts assignments to condition variables if the value can be determined\nfrom the control-flow.\n\nDestroys SSA form.\n\nCurrently, this tool is very limited, mostly because we do not yet have support\nfor boolean types. Since conditions only check for expressions being nonzero,\nwe cannot assign a specific value.\n\nCurrent features:\n\n- ``switch`` cases: insert `` := ``\n- after ``if`` statement with terminating control-flow, insert `` := 0``\n\nFuture features:\n\n- allow replacements by ``1``\n- take termination of user-defined functions into account\n\nWorks best with SSA form and if dead code removal has run before.\n\nPrerequisite: Disambiguator.\n\n.. _conditional-unsimplifier:\n\nConditionalUnsimplifier\n^^^^^^^^^^^^^^^^^^^^^^^\n\nReverse of ConditionalSimplifier.\n\n.. _control-flow-simplifier:\n\nControlFlowSimplifier\n^^^^^^^^^^^^^^^^^^^^^\n\nSimplifies several control-flow structures:\n\n- replace ``if`` with empty body with ``pop(condition)``\n- remove empty default ``switch`` case\n- remove empty ``switch`` case if no default case exists\n- replace ``switch`` with no cases with ``pop(expression)``\n- turn ``switch`` with single case into ``if``\n- replace ``switch`` with only default case with ``pop(expression)`` and body\n- replace ``switch`` with const expr with matching case body\n- replace ``for`` with terminating control flow and without other ``break``/``continue`` by ``if``\n- remove ``leave`` at the end of a function.\n\nNone of these operations depend on the data flow. The StructuralSimplifier\nperforms similar tasks that do depend on data flow.\n\nThe ControlFlowSimplifier does record the presence or absence of ``break``\nand ``continue`` statements during its traversal.\n\nPrerequisite: Disambiguator, FunctionHoister, ForLoopInitRewriter.\n\nImportant: Introduces EVM opcodes and thus can only be used on EVM code for now.\n\n.. _dead-code-eliminator:\n\nDeadCodeEliminator\n^^^^^^^^^^^^^^^^^^\n\nThis optimization stage removes unreachable code.\n\nUnreachable code is any code within a block which is preceded by a\n``leave``, ``return``, ``invalid``, ``break``, ``continue``, ``selfdestruct``, ``revert`` or by\na call to a user-defined function that recurses infinitely.\n\nFunction definitions are retained as they might be called by earlier\ncode and thus are considered reachable.\n\nBecause variables declared in a ``for`` loop's init block have their scope extended to the loop body,\nwe require ForLoopInitRewriter to run before this step.\n\nPrerequisites: ForLoopInitRewriter, FunctionHoister, FunctionGrouper.\n\n.. _equal-store-eliminator:\n\nEqualStoreEliminator\n^^^^^^^^^^^^^^^^^^^^\n\nThis steps removes ``mstore(k, v)`` and ``sstore(k, v)`` calls if\nthere was a previous call to ``mstore(k, v)`` / ``sstore(k, v)``,\nno other store in between and the values of ``k`` and ``v`` did not change.\n\nThis simple step is effective if run after the SSATransform and the\nCommonSubexpressionEliminator, because SSA will make sure that the variables\nwill not change and the CommonSubexpressionEliminator reuses exactly the same\nvariable if the value is known to be the same.\n\nPrerequisites: Disambiguator, ForLoopInitRewriter.\n\n.. _unused-pruner:\n\nUnusedPruner\n^^^^^^^^^^^^\n\nThis step removes the definitions of all functions that are never referenced.\n\nIt also removes declarations of variables that are never referenced.\nIf a declaration assigns a value that is not movable, the expression is retained,\nbut its value is discarded.\n\nAll movable expression statements (expressions that are not assigned) are removed.\n\n.. _structural-simplifier:\n\nStructuralSimplifier\n^^^^^^^^^^^^^^^^^^^^\n\nThis is a general step that performs various kinds of simplifications on\na structural level:\n\n- replace ``if`` statement with empty body by ``pop(condition)``\n- replace ``if`` statement with true condition by its body\n- remove ``if`` statement with false condition\n- turn ``switch`` with single case into ``if``\n- replace ``switch`` with only default case by ``pop(expression)`` and body\n- replace ``switch`` with literal expression by matching case body\n- replace ``for`` loop with false condition by its initialization part\n\nThis component uses the DataflowAnalyzer.\n\n.. _block-flattener:\n\nBlockFlattener\n^^^^^^^^^^^^^^\n\nThis stage eliminates nested blocks by inserting the statements in the\ninner block at the appropriate place in the outer block. It depends on the\nFunctionGrouper and does not flatten the outermost block to keep the form\nproduced by the FunctionGrouper.\n\n.. code-block:: yul\n\n {\n {\n let x := 2\n {\n let y := 3\n mstore(x, y)\n }\n }\n }\n\nis transformed to\n\n.. code-block:: yul\n\n {\n {\n let x := 2\n let y := 3\n mstore(x, y)\n }\n }\n\nAs long as the code is disambiguated, this does not cause a problem because\nthe scopes of variables can only grow.\n\n.. _loop-invariant-code-motion:\n\nLoopInvariantCodeMotion\n^^^^^^^^^^^^^^^^^^^^^^^\nThis optimization moves movable SSA variable declarations outside the loop.\n\nOnly statements at the top level in a loop's body or post block are considered, i.e variable\ndeclarations inside conditional branches will not be moved out of the loop.\n\nExpressionSplitter and SSATransform should be run upfront to obtain better results.\n\nPrerequisites: Disambiguator, ForLoopInitRewriter, FunctionHoister.\n\n\nFunction-Level Optimizations\n----------------------------\n\n.. _function-specializer:\n\nFunctionSpecializer\n^^^^^^^^^^^^^^^^^^^\n\nThis step specializes the function with its literal arguments.\n\nIf a function, say, ``function f(a, b) { sstore (a, b) }``, is called with literal arguments, for\nexample, ``f(x, 5)``, where ``x`` is an identifier, it could be specialized by creating a new\nfunction ``f_1`` that takes only one argument, i.e.,\n\n.. code-block:: yul\n\n function f_1(a_1) {\n let b_1 := 5\n sstore(a_1, b_1)\n }\n\nOther optimization steps will be able to make more simplifications to the function. The\noptimization step is mainly useful for functions that would not be inlined.\n\nPrerequisites: Disambiguator, FunctionHoister.\n\nLiteralRematerialiser is recommended as a prerequisite, even though it's not required for\ncorrectness.\n\n.. _unused-function-parameter-pruner:\n\nUnusedFunctionParameterPruner\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis step removes unused parameters in a function.\n\nIf a parameter is unused, like ``c`` and ``y`` in, ``function f(a,b,c) -> x, y { x := div(a,b) }``, we\nremove the parameter and create a new \"linking\" function as follows:\n\n.. code-block:: yul\n\n function f(a,b) -> x { x := div(a,b) }\n function f2(a,b,c) -> x, y { x := f(a,b) }\n\nand replace all references to ``f`` by ``f2``.\nThe inliner should be run afterwards to make sure that all references to ``f2`` are replaced by\n``f``.\n\nPrerequisites: Disambiguator, FunctionHoister, LiteralRematerialiser.\n\nThe step LiteralRematerialiser is not required for correctness. It helps deal with cases such as:\n``function f(x) -> y { revert(y, y} }`` where the literal ``y`` will be replaced by its value ``0``,\nallowing us to rewrite the function.\n\n.. index:: ! UnusedStoreEliminator\n.. _unused-store-eliminator:\n\nUnusedStoreEliminator\n^^^^^^^^^^^^^^^^^^^^^\n\nOptimizer component that removes redundant ``sstore`` and memory store statements.\nIn case of an ``sstore``, if all outgoing code paths revert (due to an explicit ``revert()``, ``invalid()``, or infinite recursion) or\nlead to another ``sstore`` for which the optimizer can tell that it will overwrite the first store, the statement will be removed.\nHowever, if there is a read operation between the initial ``sstore`` and the revert, or the overwriting ``sstore``, the statement\nwill not be removed.\nSuch read operations include: external calls, user-defined functions with any storage access, and ``sload`` of a slot that cannot be\nproven to differ from the slot written by the initial ``sstore``.\n\nFor example, the following code\n\n.. code-block:: yul\n\n {\n let c := calldataload(0)\n sstore(c, 1)\n if c {\n sstore(c, 2)\n }\n sstore(c, 3)\n }\n\nwill be transformed into the code below after the UnusedStoreEliminator step is run\n\n.. code-block:: yul\n\n {\n let c := calldataload(0)\n if c { }\n sstore(c, 3)\n }\n\nFor memory store operations, things are generally simpler, at least in the outermost Yul block as all such\nstatements will be removed if they are never read from in any code path.\nAt function analysis level, however, the approach is similar to ``sstore``, as we do not know whether the memory location will\nbe read once we leave the function's scope, so the statement will be removed only if all code paths lead to a memory overwrite.\n\nBest run in SSA form.\n\nPrerequisites: Disambiguator, ForLoopInitRewriter.\n\n.. _equivalent-function-combiner:\n\nEquivalentFunctionCombiner\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIf two functions are syntactically equivalent, while allowing variable\nrenaming but not any re-ordering, then any reference to one of the\nfunctions is replaced by the other.\n\n\nThe actual removal of the function is performed by the UnusedPruner.\n\nFunction Inlining\n-----------------\n\n.. _expression-inliner:\n\nExpressionInliner\n^^^^^^^^^^^^^^^^^\n\nThis component of the optimizer performs restricted function inlining by inlining functions that can be\ninlined inside functional expressions, i.e. functions that:\n\n- return a single value.\n- have a body like ``r := ``.\n- neither reference themselves nor ``r`` in the right hand side.\n\nFurthermore, for all parameters, all of the following need to be true:\n\n- The argument is movable.\n- The parameter is either referenced less than twice in the function body, or the argument is rather cheap\n (\"cost\" of at most 1, like a constant up to ``0xff``).\n\nExample: The function to be inlined has the form of ``function f(...) -> r { r := E }`` where\n``E`` is an expression that does not reference ``r`` and all arguments in the function call are movable expressions.\n\nThe result of this inlining is always a single expression.\n\nThis component can only be used on sources with unique names.\n\n.. _full-inliner:\n\nFullInliner\n^^^^^^^^^^^\n\nThe FullInliner replaces certain calls of certain functions\nby the function's body. This is not very helpful in most cases, because\nit just increases the code size but does not have a benefit. Furthermore,\ncode is usually very expensive and we would often rather have shorter\ncode than more efficient code. In some cases, though, inlining a function\ncan have positive effects on subsequent optimizer steps. This is the case\nif one of the function arguments is a constant, for example.\n\nDuring inlining, a heuristic is used to tell if the function call\nshould be inlined or not.\nThe current heuristic does not inline into \"large\" functions unless\nthe called function is tiny. Functions that are only used once\nare inlined, as well as medium-sized functions, while function\ncalls with constant arguments allow slightly larger functions.\n\n\nIn the future, we may include a backtracking component\nthat, instead of inlining a function right away, only specializes it,\nwhich means that a copy of the function is generated where\na certain parameter is always replaced by a constant. After that,\nwe can run the optimizer on this specialized function. If it\nresults in heavy gains, the specialized function is kept,\notherwise the original function is used instead.\n\nFunctionHoister and ExpressionSplitter are recommended as prerequisites since they make the step\nmore efficient, but are not required for correctness.\nIn particular, function calls with other function calls as arguments are not inlined, but running\nExpressionSplitter beforehand ensures that there are no such calls in the input.\n\nCleanup\n-------\n\nThe cleanup is performed at the end of the optimizer run. It tries\nto combine split expressions into deeply nested ones again and also\nimproves the \"compilability\" for stack machines by eliminating\nvariables as much as possible.\n\n.. _expression-joiner:\n\nExpressionJoiner\n^^^^^^^^^^^^^^^^\n\nThis is the opposite operation of the ExpressionSplitter. It turns a sequence of\nvariable declarations that have exactly one reference into a complex expression.\nThis stage fully preserves the order of function calls and opcode executions.\nIt does not make use of any information concerning the commutativity of the opcodes;\nif moving the value of a variable to its place of use would change the order\nof any function call or opcode execution, the transformation is not performed.\n\nNote that the component will not move the assigned value of a variable assignment\nor a variable that is referenced more than once.\n\nThe snippet ``let x := add(0, 2) let y := mul(x, mload(2))`` is not transformed,\nbecause it would cause the order of the call to the opcodes ``add`` and\n``mload`` to be swapped - even though this would not make a difference\nbecause ``add`` is movable.\n\nWhen reordering opcodes like that, variable references and literals are ignored.\nBecause of that, the snippet ``let x := add(0, 2) let y := mul(x, 3)`` is\ntransformed to ``let y := mul(add(0, 2), 3)``, even though the ``add`` opcode\nwould be executed after the evaluation of the literal ``3``.\n\n.. _ssa-reverser:\n\nSSAReverser\n^^^^^^^^^^^\n\nThis is a tiny step that helps in reversing the effects of the SSATransform\nif it is combined with the CommonSubexpressionEliminator and the\nUnusedPruner.\n\nThe SSA form we generate is detrimental to code generation\nbecause it produces many local variables. It would\nbe better to just reuse existing variables with assignments instead of\nfresh variable declarations.\n\nThe SSATransform rewrites\n\n.. code-block:: yul\n\n let a := calldataload(0)\n mstore(a, 1)\n\nto\n\n.. code-block:: yul\n\n let a_1 := calldataload(0)\n let a := a_1\n mstore(a_1, 1)\n let a_2 := calldataload(0x20)\n a := a_2\n\nThe problem is that instead of ``a``, the variable ``a_1`` is used\nwhenever ``a`` was referenced. The SSATransform changes statements\nof this form by just swapping out the declaration and the assignment. The above\nsnippet is turned into\n\n.. code-block:: yul\n\n let a := calldataload(0)\n let a_1 := a\n mstore(a_1, 1)\n a := calldataload(0x20)\n let a_2 := a\n\nThis is a very simple equivalence transform, but when we now run the\nCommonSubexpressionEliminator, it will replace all occurrences of ``a_1``\nby ``a`` (until ``a`` is re-assigned). The UnusedPruner will then\neliminate the variable ``a_1`` altogether and thus fully reverse the\nSSATransform.\n\n.. _stack-compressor:\n\nStackCompressor\n^^^^^^^^^^^^^^^\n\nOne problem that makes code generation for the Ethereum Virtual Machine\nhard is the fact that there is a hard limit of 16 slots for reaching\ndown the expression stack. This more or less translates to a limit\nof 16 local variables. The stack compressor takes Yul code and\ncompiles it to EVM bytecode. Whenever the stack difference is too\nlarge, it records the function this happened in.\n\nFor each function that caused such a problem, the Rematerialiser\nis called with a special request to aggressively eliminate specific\nvariables sorted by the cost of their values.\n\nOn failure, this procedure is repeated multiple times.\n\n.. _rematerialiser:\n\nRematerialiser\n^^^^^^^^^^^^^^\n\nThe rematerialisation stage tries to replace variable references by the expression that\nwas last assigned to the variable. This is of course only beneficial if this expression\nis comparatively cheap to evaluate. Furthermore, it is only semantically equivalent if\nthe value of the expression did not change between the point of assignment and the\npoint of use. The main benefit of this stage is that it can save stack slots if it\nleads to a variable being eliminated completely (see below), but it can also\nsave a ``DUP`` opcode on the EVM if the expression is very cheap.\n\nThe Rematerialiser uses the DataflowAnalyzer to track the current values of variables,\nwhich are always movable.\nIf the value is very cheap or the variable was explicitly requested to be eliminated,\nthe variable reference is replaced by its current value.\n\n.. _for-loop-condition-out-of-body:\n\nForLoopConditionOutOfBody\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nReverses the transformation of ForLoopConditionIntoBody.\n\nFor any movable ``c``, it turns\n\n.. code-block:: none\n\n for { ... } 1 { ... } {\n if iszero(c) { break }\n ...\n }\n\ninto\n\n.. code-block:: none\n\n for { ... } c { ... } {\n ...\n }\n\nand it turns\n\n.. code-block:: none\n\n for { ... } 1 { ... } {\n if c { break }\n ...\n }\n\ninto\n\n.. code-block:: none\n\n for { ... } iszero(c) { ... } {\n ...\n }\n\nThe LiteralRematerialiser should be run before this step.\n\nCodegen-Based Optimizer Module\n==============================\n\nCurrently, the codegen-based optimizer module provides two optimizations.\n\nThe first one, available in the legacy code generator, moves literals to the right side of\ncommutative binary operators, which helps exploit their associativity.\n\nThe other one, available in the IR-based code generator, enables the use of unchecked arithmetic\nwhen generating code for incrementing the counter variable of certain idiomatic ``for`` loops.\nThis avoids wasting gas by identifying some conditions that guarantee that the counter variable\ncannot overflow.\nThis eliminates the need to use a verbose unchecked arithmetic block inside the loop body to\nincrement the counter variable.\n\n.. _unchecked-loop-optimizer:\n\nUnchecked Loop Increment\n------------------------\n\nIntroduced in Solidity ``0.8.22``, the overflow check optimization step is concerned with identifying\nthe conditions under which the ``for`` loop counter can be safely incremented\nwithout overflow checks.\n\nThis optimization is **only** applied to ``for`` loops of the general form:\n\n.. code-block:: solidity\n\n for (uint i = X; i < Y; ++i) {\n // variable i is not modified in the loop body\n }\n\nThe condition and the fact that the counter variable is only ever incremented\nguarantee that it never overflows.\nThe precise requirements for the loop to be eligible for the optimization are as follows:\n\n- The loop condition is a comparison of the form ``i < Y``, for a local counter variable ``i``\n (called the \"loop counter\" hereon) and an expression ``Y``.\n- The built-in operator ``<`` is necessarily used in the loop condition and is the only operator\n that triggers the optimization. ``<=`` and the like are intentionally excluded. Additionally,\n user-defined operators are **not** eligible.\n- The loop expression is a prefix or postfix increment of the counter variable, i.e, ``i++`` or ``++i``.\n- The loop counter is a local variable of a built-in integer type.\n- The loop counter is **not** modified by the loop body or by the expression used as the loop condition.\n- The comparison is performed on the same type as the loop counter, meaning that the type of the\n right-hand-side expression is implicitly convertible to the type of the counter, such that the latter\n is not implicitly widened before the comparison.\n\nTo clarify the last condition, consider the following example:\n\n.. code-block:: solidity\n\n for (uint8 i = 0; i < uint16(1000); i++) {\n // ...\n }\n\nIn this case, the counter ``i`` has its type implicitly converted from ``uint8``\nto ``uint16`` before the comparison and the condition is in fact never false, so\nthe overflow check for the increment cannot be removed.\n" }, { "path": "docs/internals/source_mappings.rst", "content": ".. index:: source mappings\n\n***************\nSource Mappings\n***************\n\nAs part of the AST output, the compiler provides the range of the source\ncode that is represented by the respective node in the AST. This can be\nused for various purposes ranging from static analysis tools that report\nerrors based on the AST and debugging tools that highlight local variables\nand their uses.\n\nFurthermore, the compiler can also generate a mapping from the bytecode\nto the range in the source code that generated the instruction. This is again\nimportant for static analysis tools that operate on bytecode level and\nfor displaying the current position in the source code inside a debugger\nor for breakpoint handling. This mapping also contains other information,\nlike the jump type and the modifier depth (see below).\n\nBoth kinds of source mappings use integer identifiers to refer to source files.\nThe identifier of a source file is stored in\n``output['sources'][sourceName]['id']`` where ``output`` is the output of the\nstandard-json compiler interface parsed as JSON.\nFor some utility routines, the compiler generates \"internal\" source files\nthat are not part of the original input but are referenced from the source\nmappings. These source files together with their identifiers can be\nobtained via ``output['contracts'][sourceName][contractName]['evm']['bytecode']['generatedSources']``.\n\n.. note::\n In the case of instructions that are not associated with any particular source file,\n the source mapping assigns an integer identifier of ``-1``. This may happen for\n bytecode sections stemming from compiler-generated inline assembly statements.\n\nThe source mappings inside the AST use the following\nnotation:\n\n``s:l:f``\n\nWhere ``s`` is the byte-offset to the start of the range in the source file,\n``l`` is the length of the source range in bytes and ``f`` is the source\nindex mentioned above.\n\nThe encoding in the source mapping for the bytecode is more complicated:\nIt is a list of ``s:l:f:j:m`` separated by ``;``. Each of these\nelements corresponds to an instruction, i.e. you cannot use the byte offset\nbut have to use the instruction offset (push instructions are longer than a single byte).\nThe fields ``s``, ``l`` and ``f`` are as above. ``j`` can be either\n``i``, ``o`` or ``-`` signifying whether a jump instruction goes into a\nfunction, returns from a function or is a regular jump as part of e.g. a loop.\nThe last field, ``m``, is an integer that denotes the \"modifier depth\". This depth\nis increased whenever the placeholder statement (``_``) is entered in a modifier\nand decreased when it is left again. This allows debuggers to track tricky cases\nlike the same modifier being used twice or multiple placeholder statements being\nused in a single modifier.\n\nIn order to compress these source mappings especially for bytecode, the\nfollowing rules are used:\n\n- If a field is empty, the value of the preceding element is used.\n- If a ``:`` is missing, all following fields are considered empty.\n\nThis means the following source mappings represent the same information:\n\n``1:2:1;1:9:1;2:1:2;2:1:2;2:1:2``\n\n``1:2:1;:9;2:1:2;;``\n\nImportant to note is that when the :ref:`verbatim ` builtin is used,\nthe source mappings will be invalid: The builtin is considered a single\ninstruction instead of potentially multiple.\n" }, { "path": "docs/internals/variable_cleanup.rst", "content": ".. index: variable cleanup\n\n*********************\nCleaning Up Variables\n*********************\n\nUltimately, all values in the EVM are stored in 256 bit words.\nThus, in some cases, when the type of a value has less than 256 bits,\nit is necessary to clean the remaining bits.\nThe Solidity compiler is designed to do such cleaning before any operations\nthat might be adversely affected by the potential garbage in the remaining bits.\nFor example, before writing a value to memory, the remaining bits need\nto be cleared because the memory contents can be used for computing\nhashes or sent as the data of a message call. Similarly, before\nstoring a value in the storage, the remaining bits need to be cleaned\nbecause otherwise the garbled value can be observed.\n\nNote that access via inline assembly is not considered such an operation:\nIf you use inline assembly to access Solidity variables\nshorter than 256 bits, the compiler does not guarantee that\nthe value is properly cleaned up.\n\nMoreover, we do not clean the bits if the immediately\nfollowing operation is not affected. For instance, since any non-zero\nvalue is considered ``true`` by ``JUMPI`` instruction, we do not clean\nthe boolean values before they are used as the condition for\n``JUMPI``.\n\nIn addition to the design principle above, the Solidity compiler\ncleans input data when it is loaded onto the stack.\n\nThe following table describes the cleaning rules applied to different types,\nwhere ``higher bits`` refers to the remaining bits in case the type has less than 256 bits.\n\n+---------------+---------------+-------------------------+\n|Type |Valid Values |Cleanup of Invalid Values|\n+===============+===============+=========================+\n|enum of n |0 until n - 1 |throws exception |\n|members | | |\n+---------------+---------------+-------------------------+\n|bool |0 or 1 |results in 1 |\n+---------------+---------------+-------------------------+\n|signed integers|higher bits |currently silently |\n| |set to the |signextends to a valid |\n| |sign bit |value, i.e. all higher |\n| | |bits are set to the sign |\n| | |bit; may throw an |\n| | |exception in the future |\n+---------------+---------------+-------------------------+\n|unsigned |higher bits |currently silently masks |\n|integers |zeroed |to a valid value, i.e. |\n| | |all higher bits are set |\n| | |to zero; may throw an |\n| | |exception in the future |\n+---------------+---------------+-------------------------+\n\nNote that valid and invalid values are dependent on their type size.\nConsider ``uint8``, the unsigned 8-bit type, which has the following valid values:\n\n.. code-block:: none\n\n 0000...0000 0000 0000\n 0000...0000 0000 0001\n 0000...0000 0000 0010\n ....\n 0000...0000 1111 1111\n\nAny invalid value will have the higher bits set to zero:\n\n.. code-block:: none\n\n 0101...1101 0010 1010 invalid value\n 0000...0000 0010 1010 cleaned value\n\nFor ``int8``, the signed 8-bit type, the valid values are:\n\nNegative\n\n.. code-block:: none\n\n 1111...1111 1111 1111\n 1111...1111 1111 1110\n ....\n 1111...1111 1000 0000\n\nPositive\n\n.. code-block:: none\n\n 0000...0000 0000 0000\n 0000...0000 0000 0001\n 0000...0000 0000 0010\n ....\n 0000...0000 0111 1111\n\nThe compiler will ``signextend`` the sign bit, which is 1 for negative and 0 for\npositive values, overwriting the higher bits:\n\nNegative\n\n.. code-block:: none\n\n 0010...1010 1111 1111 invalid value\n 1111...1111 1111 1111 cleaned value\n\nPositive\n\n.. code-block:: none\n\n 1101...0101 0000 0100 invalid value\n 0000...0000 0000 0100 cleaned value\n" }, { "path": "docs/introduction-to-smart-contracts.rst", "content": "###############################\nIntroduction to Smart Contracts\n###############################\n\n.. _simple-smart-contract:\n\n***********************\nA Simple Smart Contract\n***********************\n\nLet us begin with a basic example that sets the value of a variable and exposes\nit for other contracts to access. It is fine if you do not understand\neverything right now, we will go into more details later.\n\nStorage Example\n===============\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.4.16 <0.9.0;\n\n contract SimpleStorage {\n uint storedData;\n\n function set(uint x) public {\n storedData = x;\n }\n\n function get() public view returns (uint) {\n return storedData;\n }\n }\n\nThe first line tells you that the source code is licensed under the\nGPL version 3.0. Machine-readable license specifiers are important\nin a setting where publishing the source code is the default.\n\nThe next line specifies that the source code is written for\nSolidity version 0.4.16, or a newer version of the language up to, but not including version 0.9.0.\nThis is to ensure that the contract is not compilable with a new (breaking) compiler version, where it could behave differently.\n:ref:`Pragmas` are common instructions for compilers about how to treat the\nsource code (e.g. `pragma once `_).\n\nA contract in the sense of Solidity is a collection of code (its *functions*) and\ndata (its *state*) that resides at a specific address on the Ethereum\nblockchain. The line ``uint storedData;`` declares a state variable called ``storedData`` of\ntype ``uint`` (*u*\\nsigned *int*\\eger of *256* bits). You can think of it as a single slot\nin a database that you can query and alter by calling functions of the\ncode that manages the database. In this example, the contract defines the\nfunctions ``set`` and ``get`` that can be used to modify\nor retrieve the value of the variable.\n\nTo access a member (like a state variable) of the current contract, you do not typically add the ``this.`` prefix,\nyou just access it directly via its name.\nUnlike in some other languages, omitting it is not just a matter of style,\nit results in a completely different way to access the member, but more on this later.\n\nThis contract does not do much yet apart from (due to the infrastructure\nbuilt by Ethereum) allowing anyone to store a single number that is accessible by\nanyone in the world without a (feasible) way to prevent you from publishing\nthis number. Anyone could call ``set`` again with a different value\nand overwrite your number, but the number is still stored in the history\nof the blockchain. Later, you will see how you can impose access restrictions\nso that only you can alter the number.\n\n.. warning::\n Be careful with using Unicode text, as similar looking (or even identical) characters can\n have different code points and as such are encoded as a different byte array.\n\n.. note::\n All identifiers (contract names, function names and variable names) are restricted to\n the ASCII character set. It is possible to store UTF-8 encoded data in string variables.\n\n.. index:: ! subcurrency\n\nSubcurrency Example\n===================\n\nThe following contract implements the simplest form of a\ncryptocurrency. The contract allows only its creator to create new coins (different issuance schemes are possible).\nAnyone can send coins to each other without a need for\nregistering with a username and password, all you need is an Ethereum keypair.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.26;\n\n // This will only compile via IR\n contract Coin {\n // The keyword \"public\" makes variables\n // accessible from other contracts\n address public minter;\n mapping(address => uint) public balances;\n\n // Events allow clients to react to specific\n // contract changes you declare\n event Sent(address from, address to, uint amount);\n\n // Constructor code is only run when the contract\n // is created\n constructor() {\n minter = msg.sender;\n }\n\n // Sends an amount of newly created coins to an address\n // Can only be called by the contract creator\n function mint(address receiver, uint amount) public {\n require(msg.sender == minter);\n balances[receiver] += amount;\n }\n\n // Errors allow you to provide information about\n // why an operation failed. They are returned\n // to the caller of the function.\n error InsufficientBalance(uint requested, uint available);\n\n // Sends an amount of existing coins\n // from any caller to an address\n function send(address receiver, uint amount) public {\n require(amount <= balances[msg.sender], InsufficientBalance(amount, balances[msg.sender]));\n balances[msg.sender] -= amount;\n balances[receiver] += amount;\n emit Sent(msg.sender, receiver, amount);\n }\n }\n\nThis contract introduces some new concepts, let us go through them one by one.\n\nThe line ``address public minter;`` declares a state variable of type :ref:`address
`.\nThe ``address`` type is a 160-bit value that does not allow any arithmetic operations.\nIt is suitable for storing addresses of contracts, or a hash of the public half\nof a keypair belonging to :ref:`externally-owned accounts`.\n\nThe keyword ``public`` automatically generates a function that allows you to access the current value of the state\nvariable from outside of the contract. Without this keyword, other contracts have no way to access the variable.\nThe code of the function generated by the compiler is equivalent\nto the following (ignore ``external`` and ``view`` for now):\n\n.. code-block:: solidity\n\n function minter() external view returns (address) { return minter; }\n\nYou could add a function like the above yourself, but you would have a function and state variable with the same name.\nYou do not need to do this, the compiler figures it out for you.\n\n.. index:: mapping\n\nThe next line, ``mapping(address => uint) public balances;`` also\ncreates a public state variable, but it is a more complex datatype.\nThe :ref:`mapping ` type maps addresses to :ref:`unsigned integers `.\n\nMappings can be seen as `hash tables `_ which are\nvirtually initialized such that every possible key exists from the start and is mapped to a\nvalue whose byte-representation is all zeros. However, it is neither possible to obtain a list of all keys of\na mapping, nor a list of all values. Record what you\nadded to the mapping, or use it in a context where this is not needed. Or\neven better, keep a list, or use a more suitable data type.\n\nThe :ref:`getter function` created by the ``public`` keyword\nis more complex in the case of a mapping. It looks like the\nfollowing:\n\n.. code-block:: solidity\n\n function balances(address account) external view returns (uint) {\n return balances[account];\n }\n\nYou can use this function to query the balance of a single account.\n\n.. index:: event\n\nThe line ``event Sent(address from, address to, uint amount);`` declares\nan :ref:`\"event\" `, which is emitted in the last line of the function\n``send``. Ethereum clients such as web applications can\nlisten for these events emitted on the blockchain without much\ncost. As soon as it is emitted, the listener receives the\narguments ``from``, ``to`` and ``amount``, which makes it possible to track\ntransactions.\n\nTo listen for this event, you could use the following\nJavaScript code, which uses `web3.js `_ to create the ``Coin`` contract object,\nand any user interface calls the automatically generated ``balances`` function from above:\n\n.. code-block:: javascript\n\n Coin.Sent().watch({}, '', function(error, result) {\n if (!error) {\n console.log(\"Coin transfer: \" + result.args.amount +\n \" coins were sent from \" + result.args.from +\n \" to \" + result.args.to + \".\");\n console.log(\"Balances now:\\n\" +\n \"Sender: \" + Coin.balances.call(result.args.from) +\n \"Receiver: \" + Coin.balances.call(result.args.to));\n }\n })\n\n.. index:: coin\n\nThe :ref:`constructor` is a special function that is executed during the creation of the contract and\ncannot be called afterwards. In this case, it permanently stores the address of the person creating the\ncontract. The ``msg`` variable (together with ``tx`` and ``block``) is a\n:ref:`special global variable ` that\ncontains properties which allow access to the blockchain. ``msg.sender`` is\nalways the address where the current (external) function call came from.\n\nThe functions that make up the contract, and that users and contracts can call are ``mint`` and ``send``.\n\nThe ``mint`` function sends an amount of newly created coins to another address. The :ref:`require\n` function call defines conditions that reverts all changes if not met. In this\nexample, ``require(msg.sender == minter);`` ensures that only the creator of the contract can call\n``mint``. In general, the creator can mint as many tokens as they like, but at some point, this will\nlead to a phenomenon called \"overflow\". Note that because of the default :ref:`Checked arithmetic\n`, the transaction would revert if the expression ``balances[receiver] += amount;``\noverflows, i.e., when ``balances[receiver] + amount`` in arbitrary precision arithmetic is larger\nthan the maximum value of ``uint`` (``2**256 - 1``). This is also true for the statement\n``balances[receiver] += amount;`` in the function ``send``.\n\n:ref:`Errors ` allow you to provide more information to the caller about\nwhy a condition or operation failed. Errors are used together with the\n:ref:`revert statement `. The ``revert`` statement unconditionally\naborts and reverts all changes, much like the :ref:`require function `.\nBoth approaches allow you to provide the name of an error and additional data which will be supplied to the caller\n(and eventually to the front-end application or block explorer) so that\na failure can more easily be debugged or reacted upon.\n\nThe ``send`` function can be used by anyone (who already\nhas some of these coins) to send coins to anyone else. If the sender does not have\nenough coins to send, the ``if`` condition evaluates to true. As a result, the ``revert`` will cause the operation to fail\nwhile providing the sender with error details using the ``InsufficientBalance`` error.\n\n.. note::\n If you use\n this contract to send coins to an address, you will not see anything when you\n look at that address on a blockchain explorer, because the record that you sent\n coins and the changed balances are only stored in the data storage of this\n particular coin contract. By using events, you can create\n a \"blockchain explorer\" that tracks transactions and balances of your new coin,\n but you have to inspect the coin contract address and not the addresses of the\n coin owners.\n\n.. _blockchain-basics:\n\n*****************\nBlockchain Basics\n*****************\n\nBlockchains as a concept are not too hard to understand for programmers. The reason is that\nmost of the complications (mining, `hashing `_,\n`elliptic-curve cryptography `_,\n`peer-to-peer networks `_, etc.)\nare just there to provide a certain set of features and promises for the platform. Once you accept these\nfeatures as given, you do not have to worry about the underlying technology - or do you have\nto know how Amazon's AWS works internally in order to use it?\n\n.. index:: transaction\n\nTransactions\n============\n\nA blockchain is a globally shared, transactional database.\nThis means that everyone can read entries in the database just by participating in the network.\nIf you want to change something in the database, you have to create a so-called transaction\nwhich has to be accepted by all others.\nThe word transaction implies that the change you want to make (assume you want to change\ntwo values at the same time) is either not done at all or completely applied. Furthermore,\nwhile your transaction is being applied to the database, no other transaction can alter it.\n\nAs an example, imagine a table that lists the balances of all accounts in an\nelectronic currency. If a transfer from one account to another is requested,\nthe transactional nature of the database ensures that if the amount is\nsubtracted from one account, it is always added to the other account. If due\nto whatever reason, adding the amount to the target account is not possible,\nthe source account is also not modified.\n\nFurthermore, a transaction is always cryptographically signed by the sender (creator).\nThis makes it straightforward to guard access to specific modifications of the\ndatabase. In the example of the electronic currency, a simple check ensures that\nonly the person holding the keys to the account can transfer some compensation, e.g. Ether, from it.\n\n.. index:: ! block\n\nBlocks\n======\n\nOne major obstacle to overcome is what (in Bitcoin terms) is called a \"double-spend attack\":\nWhat happens if two transactions exist in the network that both want to empty an account?\nOnly one of the transactions can be valid, typically the one that is accepted first.\nThe problem is that \"first\" is not an objective term in a peer-to-peer network.\n\nThe abstract answer to this is that you do not have to care. A globally accepted order of the transactions\nwill be selected for you, solving the conflict. The transactions will be bundled into what is called a \"block\"\nand then they will be executed and distributed among all participating nodes.\nIf two transactions contradict each other, the one that ends up being second will\nbe rejected and not become part of the block.\n\nThese blocks form a linear sequence in time, and that is where the word \"blockchain\" derives from.\nBlocks are added to the chain at regular intervals, although these intervals may be subject to change in the future.\nFor the most up-to-date information, it is recommended to monitor the network, for example, on `Etherscan `_.\n\nAs part of the \"order selection mechanism\", which is called `attestation `_, it may happen that\nblocks are reverted from time to time, but only at the \"tip\" of the chain. The more\nblocks are added on top of a particular block, the less likely this block will be reverted. So it might be that your transactions\nare reverted and even removed from the blockchain, but the longer you wait, the less\nlikely it will be.\n\n.. note::\n Transactions are not guaranteed to be included in the next block or any specific future block,\n since it is not up to the submitter of a transaction, but up to the miners to determine in which block the transaction is included.\n\n If you want to schedule future calls of your contract, you can use\n a smart contract automation tool or an oracle service.\n\n.. _the-ethereum-virtual-machine:\n\n.. index:: !evm, ! ethereum virtual machine\n\n****************************\nThe Ethereum Virtual Machine\n****************************\n\nOverview\n========\n\nThe Ethereum Virtual Machine or EVM is the runtime environment\nfor smart contracts in Ethereum. It is not only sandboxed but\nactually completely isolated, which means that code running\ninside the EVM has no access to network, filesystem or other processes.\nSmart contracts even have limited access to other smart contracts.\n\n.. index:: ! account, address, storage, balance\n\n.. _accounts:\n\nAccounts\n========\n\nThere are two kinds of accounts in Ethereum which share the same\naddress space: **Externally-owned accounts** that are controlled by\npublic-private key pairs (i.e. humans) and **contract accounts** which are\ncontrolled by the code stored together with the account.\n\nThe address of an externally-owned account is determined from\nthe public key while the address of a contract is\ndetermined at the time the contract is created\n(it is derived from the creator address and the number\nof transactions sent from that address, the so-called \"nonce\").\n\nRegardless of whether or not the account stores code, the two types are\ntreated equally by the EVM.\n\nEvery account has a persistent key-value store mapping 256-bit words to 256-bit\nwords called **storage**.\n\nFurthermore, every account has a **balance** in\nEther (in \"Wei\" to be exact, ``1 ether`` is ``10**18 wei``) which can be modified by sending transactions that\ninclude Ether.\n\n.. index:: ! transaction\n\nTransactions\n============\n\nA transaction is a message that is sent from one account to another\naccount (which might be the same or empty, see below).\nIt can include binary data (which is called \"payload\") and Ether.\n\nIf the target account contains code, that code is executed and\nthe payload is provided as input data.\n\nIf the target account is not set (the transaction does not have\na recipient or the recipient is set to ``null``), the transaction\ncreates a **new contract**.\nAs already mentioned, the address of that contract is not\nthe zero address but an address derived from the sender and\nits number of transactions sent (the \"nonce\"). The payload\nof such a contract creation transaction is taken to be\nEVM bytecode and executed. The output data of this execution is\npermanently stored as the code of the contract.\nThis means that in order to create a contract, you do not\nsend the actual code of the contract, but in fact code that\nreturns that code when executed.\n\n.. note::\n While a contract is being created, its code is still empty.\n Because of that, you should not call back into the\n contract under construction until its constructor has\n finished executing.\n\n.. index:: ! gas, ! gas price\n\nGas\n===\n\nUpon creation, each transaction is charged with a certain amount of **gas**\nthat has to be paid for by the originator of the transaction (``tx.origin``).\nWhile the EVM executes the\ntransaction, the gas is gradually depleted according to specific rules.\nIf the gas is used up at any point (i.e. it would be negative),\nan out-of-gas exception is triggered, which ends execution and reverts all modifications\nmade to the state in the current call frame.\n\nThis mechanism incentivizes economical use of EVM execution time\nand also compensates EVM executors (i.e. miners / stakers) for their work.\nSince each block has a maximum amount of gas, it also limits the amount\nof work needed to validate a block.\n\nThe **gas price** is a value set by the originator of the transaction, who\nhas to pay ``gas_price * gas`` up front to the EVM executor.\nIf some gas is left after execution, it is refunded to the transaction originator.\nIn case of an exception that reverts changes, already used up gas is not refunded.\n\nSince EVM executors can choose to include a transaction or not,\ntransaction senders cannot abuse the system by setting a low gas price.\n\n.. index:: ! storage, ! memory, ! stack, ! transient storage\n\n.. _locations:\n\nStorage, Transient Storage, Memory and the Stack\n================================================\n\nThe Ethereum Virtual Machine has different areas where it can store data with the most\nprominent being storage, transient storage, memory and the stack.\n\nEach account has a data area called **storage**, which is persistent between function calls\nand transactions.\nStorage is a key-value store that maps 256-bit words to 256-bit words.\nIt is not possible to enumerate storage from within a contract, it is\ncomparatively costly to read, and even more to initialise and modify storage. Because of this cost,\nyou should minimize what you store in persistent storage to what the contract needs to run.\nStore data like derived calculations, caching, and aggregates outside of the contract.\nA contract can neither read nor write to any storage apart from its own.\n\nSimilar to storage, there is another data area called **transient storage**,\nwhere the main difference is that it is reset at the end of each transaction.\nThe values stored in this data location persist only across function calls originating\nfrom the first call of the transaction.\nWhen the transaction ends, the transient storage is reset and the values stored there\nbecome unavailable to calls in subsequent transactions.\nDespite this, the cost of reading and writing to transient storage is significantly lower than for storage.\n\nThe third data area is called **memory**, of which a contract obtains\na freshly cleared instance for each message call. Memory is linear and can be\naddressed at byte level, but reads are limited to a width of 256 bits, while writes\ncan be either 8 bits or 256 bits wide. Memory is expanded by a word (256-bit), when\naccessing (either reading or writing) a previously untouched memory word (i.e. any offset\nwithin a word). At the time of expansion, the cost in gas must be paid. Memory is more\ncostly the larger it grows (it scales quadratically).\n\nThe EVM is not a register machine but a stack machine, so all\ncomputations are performed on a data area called the **stack**. It has a maximum size of\n1024 elements and contains words of 256 bits. Access to the stack is\nlimited to the top end in the following way:\nIt is possible to copy one of\nthe topmost 16 elements to the top of the stack or swap the\ntopmost element with one of the 16 elements below it.\nAll other operations take the topmost two (or one, or more, depending on\nthe operation) elements from the stack and push the result onto the stack.\nOf course it is possible to move stack elements to storage or memory\nin order to get deeper access to the stack,\nbut it is not possible to just access arbitrary elements deeper in the stack\nwithout first removing the top of the stack.\n\nCalldata, Returndata and Code\n=============================\n\nThere are also other data areas which are not as apparent as those discussed previously.\nHowever, they are routinely used during the execution of smart contract transactions.\n\nThe calldata region is the data sent to a transaction as part of a smart contract transaction.\nFor example, when creating a contract, calldata would be the constructor code of the new contract.\nThe parameters of external functions are always initially stored in calldata in an ABI-encoded form\nand only then decoded into the location specified in their declaration.\nIf declared as ``memory``, the compiler will eagerly decode them into memory at the beginning of the function,\nwhile marking them as ``calldata`` means that this will be done lazily, only when accessed.\nValue types and ``storage`` pointers are decoded directly onto the stack.\n\nThe returndata is the way a smart contract can return a value after a call.\nIn general, external Solidity functions use the ``return`` keyword to ABI-encode values into the returndata area.\n\nThe code is the region where the EVM instructions of a smart contract are stored.\nCode is the bytes read, interpreted, and executed by the EVM during smart contract execution.\nInstruction data stored in the code is persistent as part of a contract account state field.\nImmutable and constant variables are stored in the code region.\nAll references to immutables are replaced with the values assigned to them.\nA similar process is performed for constants which have their expressions inlined\nin the places where they are referenced in the smart contract code.\n\n.. index:: ! instruction\n\nInstruction Set\n===============\n\nThe instruction set of the EVM is kept minimal in order to avoid\nincorrect or inconsistent implementations which could cause consensus problems.\nAll instructions operate on the basic data type, 256-bit words or on slices of memory\n(or other byte arrays).\nThe usual arithmetic, bit, logical and comparison operations are present.\nConditional and unconditional jumps are possible. Furthermore,\ncontracts can access relevant properties of the current block\nlike its number and timestamp.\n\nFor a complete list, please see the :ref:`list of opcodes ` as part of the inline\nassembly documentation.\n\n.. index:: ! message call, function;call\n\nMessage Calls\n=============\n\nContracts can call other contracts or send Ether to non-contract\naccounts by the means of message calls. Message calls are similar\nto transactions, in that they have a source, a target, data payload,\nEther, gas and return data. In fact, every transaction consists of\na top-level message call which in turn can create further message calls.\n\nA contract can decide how much of its remaining **gas** should be sent\nwith the inner message call and how much it wants to retain.\nIf an out-of-gas exception happens in the inner call (or any\nother exception), this will be signaled by an error value put onto the stack.\nIn this case, only the gas sent together with the call is used up.\nIn Solidity, the calling contract causes a manual exception by default in\nsuch situations, so that exceptions \"bubble up\" the call stack.\n\nAs already said, the called contract (which can be the same as the caller)\nwill receive a freshly cleared instance of memory and has access to the\ncall payload - which will be provided in a separate area called the **calldata**.\nAfter it has finished execution, it can return data which will be stored at\na location in the caller's memory preallocated by the caller.\nAll such calls are fully synchronous.\n\nCalls are **limited** to a depth of 1024, which means that for more complex\noperations, loops should be preferred over recursive calls. Furthermore,\nonly 63/64th of the gas can be forwarded in a message call, which causes a\ndepth limit of a little less than 1000 in practice.\n\n.. _delegatecall:\n.. index:: delegatecall, library\n\nDelegatecall and Libraries\n==========================\n\nThere exists a special variant of a message call, named **delegatecall**\nwhich is identical to a message call apart from the fact that\nthe code at the target address is executed in the context (i.e. at the address) of the calling\ncontract and ``msg.sender`` and ``msg.value`` do not change their values.\n\nThis means that a contract can dynamically load code from a different\naddress at runtime. Storage, current address and balance still\nrefer to the calling contract, only the code is taken from the called address.\n\nThis makes it possible to implement the \"library\" feature in Solidity:\nReusable library code that can be applied to a contract's storage, e.g. in\norder to implement a complex data structure.\n\n.. index:: log\n\nLogs\n====\n\nIt is possible to store data in a specially indexed data structure\nthat maps all the way up to the block level. This feature called **logs**\nis used by Solidity in order to implement :ref:`events `.\nContracts cannot access log data after it has been created, but they\ncan be efficiently accessed from outside the blockchain.\nSince some part of the log data is stored in `bloom filters `_, it is\npossible to search for this data in an efficient and cryptographically\nsecure way, so network peers that do not download the whole blockchain\n(so-called \"light clients\") can still find these logs.\n\n.. index:: contract creation\n\nCreate\n======\n\nContracts can even create other contracts using a special opcode (i.e.\nthey do not simply call the zero address as a transaction would). The only difference between\nthese **create calls** and normal message calls is that the payload data is\nexecuted and the result stored as code and the caller / creator\nreceives the address of the new contract on the stack.\n\n.. index:: ! selfdestruct, deactivate\n\nDeactivate and Self-destruct\n============================\n\nThe only way to remove code from the blockchain is when a contract at that\naddress performs the ``selfdestruct`` operation. The remaining Ether stored\nat that address is sent to a designated target and then the storage and code\nis removed from the state. Removing the contract in theory sounds like a good\nidea, but it is potentially dangerous, as if someone sends Ether to removed\ncontracts, the Ether is forever lost.\n\n.. warning::\n From ``EVM >= Cancun`` onwards, ``selfdestruct`` will **only** send all Ether in the account to the given recipient and not destroy the contract.\n However, when ``selfdestruct`` is called in the same transaction that creates the contract calling it,\n the behaviour of ``selfdestruct`` before Cancun hardfork (i.e., ``EVM <= Shanghai``) is preserved and will destroy the current contract,\n deleting any data, including storage keys, code and the account itself.\n See `EIP-6780 `_ for more details.\n\n The new behaviour is the result of a network-wide change that affects all contracts present on\n the Ethereum mainnet and testnets.\n It is important to note that this change is dependent on the EVM version of the chain on which\n the contract is deployed.\n The ``--evm-version`` setting used when compiling the contract has no bearing on it.\n\n Also, note that the ``selfdestruct`` opcode has been deprecated in Solidity version 0.8.18,\n as recommended by `EIP-6049 `_.\n The deprecation is still in effect and the compiler will still emit warnings on its use.\n Any use in newly deployed contracts is strongly discouraged even if the new behavior is taken into account.\n Future changes to the EVM might further reduce the functionality of the opcode.\n\n.. warning::\n Even if a contract is removed by ``selfdestruct``, it is still part of the\n history of the blockchain and probably retained by most Ethereum nodes.\n So using ``selfdestruct`` is not the same as deleting data from a hard disk.\n\n.. note::\n Even if a contract's code does not contain a call to ``selfdestruct``,\n it can still perform that operation using ``delegatecall`` or ``callcode``.\n\nIf you want to deactivate your contracts, you should instead **disable** them\nby changing some internal state which causes all functions to revert. This\nmakes it impossible to use the contract, as it returns Ether immediately.\n\n\n.. index:: ! precompiled contracts, ! precompiles, ! contract;precompiled\n\n.. _precompiledContracts:\n\nPrecompiled Contracts\n=====================\n\nThere is a small set of contract addresses that are special:\nThe address range between ``1`` and (including) ``0x0a`` contains\n\"precompiled contracts\" that can be called as any other contract\nbut their behavior (and their gas consumption) is not defined\nby EVM code stored at that address (they do not contain code)\nbut instead is implemented in the EVM execution environment itself.\n\nDifferent EVM-compatible chains might use a different set of\nprecompiled contracts. It might also be possible that new\nprecompiled contracts are added to the Ethereum main chain in the future,\nbut you can reasonably expect them to always be in the range between\n``1`` and ``0xffff`` (inclusive).\n" }, { "path": "docs/ir-breaking-changes.rst", "content": "\n.. index: ir breaking changes\n\n.. _ir-breaking-changes:\n\n*********************************\nSolidity IR-based Codegen Changes\n*********************************\n\nSolidity can generate EVM bytecode in two different ways:\nEither directly from Solidity to EVM opcodes (\"old codegen\") or through\nan intermediate representation (\"IR\") in Yul (\"new codegen\" or \"IR-based codegen\").\n\nThe IR-based code generator was introduced with an aim to not only allow\ncode generation to be more transparent and auditable but also\nto enable more powerful optimization passes that span across functions.\n\nYou can enable it on the command-line using ``--via-ir``\nor with the option ``{\"viaIR\": true}`` in standard-json and we\nencourage everyone to try it out!\n\nFor several reasons, there are tiny semantic differences between the old\nand the IR-based code generator, mostly in areas where we would not\nexpect people to rely on this behavior anyway.\nThis section highlights the main differences between the old and the IR-based codegen.\n\nSemantic Only Changes\n=====================\n\nThis section lists the changes that are semantic-only, thus potentially\nhiding new and different behavior in existing code.\n\n.. _state-variable-initialization-order:\n\n- The order of state variable initialization has changed in case of inheritance.\n\n The order used to be:\n\n - All state variables are zero-initialized at the beginning.\n - Evaluate base constructor arguments from most derived to most base contract.\n - Initialize all state variables in the whole inheritance hierarchy from most base to most derived.\n - Run the constructor, if present, for all contracts in the linearized hierarchy from most base to most derived.\n\n New order:\n\n - All state variables are zero-initialized at the beginning.\n - Evaluate base constructor arguments from most derived to most base contract.\n - For every contract in order from most base to most derived in the linearized hierarchy:\n\n 1. Initialize state variables.\n 2. Run the constructor (if present).\n\n This causes differences in contracts where the initial value of a state\n variable relies on the result of the constructor in another contract:\n\n .. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.1;\n\n contract A {\n uint x;\n constructor() {\n x = 42;\n }\n function f() public view returns(uint256) {\n return x;\n }\n }\n contract B is A {\n uint public y = f();\n }\n\n Previously, ``y`` would be set to 0. This is due to the fact that we would first initialize state variables: First, ``x`` is set to 0, and when initializing ``y``, ``f()`` would return 0 causing ``y`` to be 0 as well.\n With the new rules, ``y`` will be set to 42. We first initialize ``x`` to 0, then call A's constructor which sets ``x`` to 42. Finally, when initializing ``y``, ``f()`` returns 42 causing ``y`` to be 42.\n\n- When storage structs are deleted, every storage slot that contains\n a member of the struct is set to zero entirely. Formerly, padding space\n was left untouched.\n Consequently, if the padding space within a struct is used to store data\n (e.g. in the context of a contract upgrade), you have to be aware that\n ``delete`` will now also clear the added member (while it wouldn't\n have been cleared in the past).\n\n .. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.1;\n\n contract C {\n struct S {\n uint64 y;\n uint64 z;\n }\n S s;\n function f() public {\n // ...\n delete s;\n // s occupies only first 16 bytes of the 32 bytes slot\n // delete will write zero to the full slot\n }\n }\n\n We have the same behavior for implicit delete, for example when array of structs is shortened.\n\n- Function modifiers are implemented in a slightly different way regarding function parameters and return variables.\n This especially has an effect if the placeholder ``_;`` is evaluated multiple times in a modifier.\n In the old code generator, each function parameter and return variable has a fixed slot on the stack.\n If the function is run multiple times because ``_;`` is used multiple times or used in a loop, then a\n change to the function parameter's or return variable's value is visible in the next execution of the function.\n The new code generator implements modifiers using actual functions and passes function parameters on.\n This means that multiple evaluations of a function's body will get the same values for the parameters,\n and the effect on return variables is that they are reset to their default (zero) value for each\n execution.\n\n .. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0;\n contract C {\n function f(uint a) public pure mod() returns (uint r) {\n r = a++;\n }\n modifier mod() { _; _; }\n }\n\n If you execute ``f(0)`` in the old code generator, it will return ``1``, while\n it will return ``0`` when using the new code generator.\n\n .. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.1 <0.9.0;\n\n contract C {\n bool active = true;\n modifier mod()\n {\n _;\n active = false;\n _;\n }\n function foo() external mod() returns (uint ret)\n {\n if (active)\n ret = 1; // Same as ``return 1``\n }\n }\n\n The function ``C.foo()`` returns the following values:\n\n - Old code generator: ``1`` as the return variable is initialized to ``0`` only once before the first ``_;``\n evaluation and then overwritten by the ``return 1;``. It is not initialized again for the second ``_;``\n evaluation and ``foo()`` does not explicitly assign it either (due to ``active == false``), thus it keeps\n its first value.\n - New code generator: ``0`` as all parameters, including return parameters, will be re-initialized before\n each ``_;`` evaluation.\n\n .. index:: ! evaluation order; expression\n\n- For the old code generator, the evaluation order of expressions is unspecified.\n For the new code generator, we try to evaluate in source order (left to right), but do not guarantee it.\n This can lead to semantic differences.\n\n For example:\n\n .. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.1;\n contract C {\n function preincr_u8(uint8 a) public pure returns (uint8) {\n return ++a + a;\n }\n }\n\n The function ``preincr_u8(1)`` returns the following values:\n\n - Old code generator: ``3`` (``1 + 2``) but the return value is unspecified in general\n - New code generator: ``4`` (``2 + 2``) but the return value is not guaranteed\n\n .. index:: ! evaluation order; function arguments\n\n On the other hand, function argument expressions are evaluated in the same order\n by both code generators with the exception of the global functions ``addmod`` and ``mulmod``.\n For example:\n\n .. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.1;\n contract C {\n function add(uint8 a, uint8 b) public pure returns (uint8) {\n return a + b;\n }\n function g(uint8 a, uint8 b) public pure returns (uint8) {\n return add(++a + ++b, a + b);\n }\n }\n\n The function ``g(1, 2)`` returns the following values:\n\n - Old code generator: ``10`` (``add(2 + 3, 2 + 3)``) but the return value is unspecified in general\n - New code generator: ``10`` but the return value is not guaranteed\n\n The arguments to the global functions ``addmod`` and ``mulmod`` are evaluated right-to-left by the old code generator\n and left-to-right by the new code generator.\n For example:\n\n .. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.1;\n contract C {\n function f() public pure returns (uint256 aMod, uint256 mMod) {\n uint256 x = 3;\n // Old code gen: add/mulmod(5, 4, 3)\n // New code gen: add/mulmod(4, 5, 5)\n aMod = addmod(++x, ++x, x);\n mMod = mulmod(++x, ++x, x);\n }\n }\n\n The function ``f()`` returns the following values:\n\n - Old code generator: ``aMod = 0`` and ``mMod = 2``\n - New code generator: ``aMod = 4`` and ``mMod = 0``\n\n- The new code generator imposes a hard limit of ``type(uint64).max``\n (``0xffffffffffffffff``) for the free memory pointer. Allocations that would\n increase its value beyond this limit revert. The old code generator does not\n have this limit.\n\n For example:\n\n .. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >0.8.0;\n contract C {\n function f() public {\n uint[] memory arr;\n // allocation size: 576460752303423481\n // assumes freeMemPtr points to 0x80 initially\n uint solYulMaxAllocationBeforeMemPtrOverflow = (type(uint64).max - 0x80 - 31) / 32;\n // freeMemPtr overflows UINT64_MAX\n arr = new uint[](solYulMaxAllocationBeforeMemPtrOverflow);\n }\n }\n\n The function ``f()`` behaves as follows:\n\n - Old code generator: runs out of gas while zeroing the array contents after the large memory allocation\n - New code generator: reverts due to free memory pointer overflow (does not run out of gas)\n\n\nInternals\n=========\n\n.. _internal-function-pointers-in-ir:\n\nInternal function pointers\n--------------------------\n\n.. index:: function pointers\n\nThe old code generator uses code offsets or tags for values of internal function pointers. This is especially complicated since\nthese offsets are different at construction time and after deployment and the values can cross this border via storage.\nBecause of that, both offsets are encoded at construction time into the same value (into different bytes).\n\nIn the new code generator, function pointers use internal IDs that are allocated in sequence. Since calls via jumps are not possible,\ncalls through function pointers always have to use an internal dispatch function that uses the ``switch`` statement to select\nthe right function.\n\nThe ID ``0`` is reserved for uninitialized function pointers which then cause a panic in the dispatch function when called.\n\nIn the old code generator, internal function pointers are initialized with a special function that always causes a panic.\nThis causes a storage write at construction time for internal function pointers in storage.\n\n.. note::\n The compiler is free to omit internal functions that are never explicitly referenced by name.\n As a consequence, assigning to a function type variable in inline assembly does not guarantee\n that the assigned value will be included in the internal dispatch.\n The function must also be explicitly referenced elsewhere in the code.\n\nCleanup\n-------\n\n.. index:: cleanup, dirty bits\n\nThe old code generator only performs cleanup before an operation whose result could be affected by the values of the dirty bits.\nThe new code generator performs cleanup after any operation that can result in dirty bits.\nThe hope is that the optimizer will be powerful enough to eliminate redundant cleanup operations.\n\nFor example:\n\n.. code-block:: solidity\n :force:\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.1;\n contract C {\n function f(uint8 a) public pure returns (uint r1, uint r2)\n {\n a = ~a;\n assembly {\n r1 := a\n }\n r2 = a;\n }\n }\n\nThe function ``f(1)`` returns the following values:\n\n- Old code generator: (``fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe``, ``00000000000000000000000000000000000000000000000000000000000000fe``)\n- New code generator: (``00000000000000000000000000000000000000000000000000000000000000fe``, ``00000000000000000000000000000000000000000000000000000000000000fe``)\n\nNote that, unlike the new code generator, the old code generator does not perform a cleanup after the bit-not assignment (``a = ~a``).\nThis results in different values being assigned (within the inline assembly block) to return value ``r1`` between the old and new code generators.\nHowever, both code generators perform a cleanup before the new value of ``a`` is assigned to ``r2``.\n" }, { "path": "docs/language-influences.rst", "content": "###################\nLanguage Influences\n###################\n\nSolidity is a `curly-bracket language `_\nthat has been influenced and inspired by several well-known programming languages.\n\nSolidity is most profoundly influenced by C++, but also borrowed concepts from languages like\nPython, JavaScript, and others.\n\nThe influence from C++ can be seen in the syntax for variable declarations, for loops, the concept\nof overloading functions, implicit and explicit type conversions and many other details.\n\nIn the early days of the language, Solidity used to be partly influenced by JavaScript.\nThis was due to function-level scoping of variables and the use of the keyword ``var``.\nThe JavaScript influence was reduced starting from version 0.4.0.\nNow, the main remaining similarity to JavaScript is that functions are defined using the keyword\n``function``. Solidity also supports import syntax and semantics that\nare similar to those available in JavaScript. Besides those points, Solidity looks like\nmost other curly-bracket languages and has no major JavaScript influence anymore.\n\nAnother influence to Solidity was Python. Solidity's modifiers were added trying to model\nPython's decorators with a much more restricted functionality. Furthermore, multiple inheritance, C3 linearization,\nand the ``super`` keyword are taken from Python as well as the general assignment and copy semantics of value\nand reference types.\n" }, { "path": "docs/layout-of-source-files.rst", "content": "********************************\nLayout of a Solidity Source File\n********************************\n\nSource files can contain an arbitrary number of\n:ref:`contract definitions`, import_ ,\n:ref:`pragma` and :ref:`using for` directives and\n:ref:`struct`, :ref:`enum`, :ref:`function`, :ref:`error`\nand :ref:`constant variable` definitions.\n\n.. index:: ! license, spdx\n\nSPDX License Identifier\n=======================\n\nTrust in smart contracts can be better established if their source code\nis available. Since making source code available always touches on legal problems\nwith regards to copyright, the Solidity compiler encourages the use\nof machine-readable `SPDX license identifiers `_.\nEvery source file should start with a comment indicating its license:\n\n``// SPDX-License-Identifier: MIT``\n\nThe compiler does not validate that the license is part of the\n`list allowed by SPDX `_, but\nit does include the supplied string in the :ref:`bytecode metadata `.\n\nIf you do not want to specify a license or if the source code is\nnot open-source, please use the special value ``UNLICENSED``.\nNote that ``UNLICENSED`` (no usage allowed, not present in SPDX license list)\nis different from ``UNLICENSE`` (grants all rights to everyone).\nSolidity follows `the npm recommendation `_.\n\nSupplying this comment of course does not free you from other\nobligations related to licensing like having to mention\na specific license header in each source file or the\noriginal copyright holder.\n\nThe comment is recognized by the compiler anywhere in the file at the\nfile level, but it is recommended to put it at the top of the file.\n\nMore information about how to use SPDX license identifiers\ncan be found at the `SPDX website `_.\n\n\n.. index:: ! pragma\n\n.. _pragma:\n\nPragmas\n=======\n\nThe ``pragma`` keyword is used to enable certain compiler features\nor checks. A pragma directive is always local to a source file, so\nyou have to add the pragma to all your files if you want to enable it\nin your whole project. If you :ref:`import` another file, the pragma\nfrom that file does *not* automatically apply to the importing file.\n\n.. index:: ! pragma;version\n\n.. _version_pragma:\n\nVersion Pragma\n--------------\n\nSource files can (and should) be annotated with a version pragma to reject\ncompilation with future compiler versions that might introduce incompatible\nchanges. We try to keep these to an absolute minimum and\nintroduce them in a way that changes in semantics also require changes\nin the syntax, but this is not always possible. Because of this, it is always\na good idea to read through the changelog at least for releases that contain\nbreaking changes. These releases always have versions of the form\n``0.x.0`` or ``x.0.0``.\n\nThe version pragma is used as follows: ``pragma solidity ^0.5.2;``\n\nA source file with the line above does not compile with a compiler earlier than version 0.5.2,\nand it also does not work on a compiler starting from version 0.6.0 (this\nsecond condition is added by using ``^``). Because\nthere will be no breaking changes until version ``0.6.0``, you can\nbe sure that your code compiles the way you intended. The exact version of the\ncompiler is not fixed, so that bugfix releases are still possible.\n\nIt is possible to specify more complex rules for the compiler version,\nthese follow the same syntax used by `npm `_.\n\n.. note::\n Using the version pragma *does not* change the version of the compiler.\n It also *does not* enable or disable features of the compiler. It just\n instructs the compiler to check whether its version matches the one\n required by the pragma. If it does not match, the compiler issues\n an error.\n\n.. index:: ! ABI coder, ! pragma; abicoder, pragma; ABIEncoderV2\n.. _abi_coder:\n\nABI Coder Pragma\n----------------\n\nBy using ``pragma abicoder v1`` or ``pragma abicoder v2`` you can\nselect between the two implementations of the ABI encoder and decoder.\n\nThe new ABI coder (v2) is able to encode and decode arbitrarily nested\narrays and structs. Apart from supporting more types, it involves more extensive\nvalidation and safety checks, which may result in higher gas costs, but also heightened\nsecurity.\nIt is considered non-experimental as of Solidity 0.6.0 and it is enabled by default starting\nwith Solidity 0.8.0. The old ABI coder can still be selected using ``pragma abicoder v1;``.\n\n.. warning::\n The ABI coder v1 is deprecated and scheduled for removal.\n Use ABI coder v2 instead.\n\nThe set of types supported by the new encoder is a strict superset of\nthe ones supported by the old one. Contracts that use it can interact with ones\nthat do not without limitations. The reverse is possible only as long as the\nnon-``abicoder v2`` contract does not try to make calls that would require\ndecoding types only supported by the new encoder. The compiler can detect this\nand will issue an error. Simply enabling ``abicoder v2`` for your contract is\nenough to make the error go away.\n\n.. note::\n This pragma applies to all the code defined in the file where it is activated,\n regardless of where that code ends up eventually. This means that a contract\n whose source file is selected to compile with ABI coder v1\n can still contain code that uses the new encoder\n by inheriting it from another contract. This is allowed if the new types are only\n used internally and not in external function signatures.\n\n.. note::\n Up to Solidity 0.7.4, it was possible to select the ABI coder v2\n by using ``pragma experimental ABIEncoderV2``, but it was not possible\n to explicitly select coder v1 because it was the default.\n\n.. index:: ! pragma; experimental\n.. _experimental_pragma:\n\nExperimental Pragma\n-------------------\n\nThe second pragma is the experimental pragma. It can be used to enable\nfeatures of the compiler or language that are not yet enabled by default.\nThe following experimental pragmas are currently supported:\n\n.. index:: ! pragma; ABIEncoderV2\n\nABIEncoderV2\n~~~~~~~~~~~~\n\nBecause the ABI coder v2 is not considered experimental anymore,\nit can be selected via ``pragma abicoder v2`` (please see above)\nsince Solidity 0.7.4.\n\n.. index:: ! pragma; SMTChecker\n.. _smt_checker:\n\nSMTChecker\n~~~~~~~~~~\n\nIf you use ``pragma experimental SMTChecker;``, then you get additional\n:ref:`safety warnings` which are obtained by querying an\nSMT solver.\nThe component does not yet support all features of the Solidity language and\nlikely outputs many warnings. In case it reports unsupported features, the\nanalysis may not be fully sound.\n\n.. note::\n\n The ``SMTChecker`` pragma is deprecated and will be removed.\n To enable SMTChecker, simply select :ref:`select an engine` when invoking the compiler.\n\n.. index:: source file, ! import, module, source unit\n\n.. _import:\n\nImporting other Source Files\n============================\n\nSyntax and Semantics\n--------------------\n\nSolidity supports import statements to help modularise your code that\nare similar to those available in JavaScript\n(from ES6 on). However, Solidity does not support the concept of\na `default export `_.\n\nAt a global level, you can use import statements of the following form:\n\n.. code-block:: solidity\n\n import \"filename\";\n\nThe ``filename`` part is called an *import path*.\nThis statement imports all global symbols from \"filename\" (and symbols imported there) into the\ncurrent global scope (different than in ES6 but backwards-compatible for Solidity).\nThis form is not recommended for use, because it unpredictably pollutes the namespace.\nIf you add new top-level items inside \"filename\", they automatically\nappear in all files that import like this from \"filename\". It is better to import specific\nsymbols explicitly.\n\nThe following example creates a new global symbol ``symbolName`` whose members are all\nthe global symbols from ``\"filename\"``:\n\n.. code-block:: solidity\n\n import * as symbolName from \"filename\";\n\nwhich results in all global symbols being available in the format ``symbolName.symbol``.\n\nA variant of this syntax that is not part of ES6, but possibly useful is:\n\n.. code-block:: solidity\n\n import \"filename\" as symbolName;\n\nwhich is equivalent to ``import * as symbolName from \"filename\";``.\n\nIf there is a naming collision, you can rename symbols while importing. For example,\nthe code below creates new global symbols ``alias`` and ``symbol2`` which reference\n``symbol1`` and ``symbol2`` from inside ``\"filename\"``, respectively.\n\n.. code-block:: solidity\n\n import {symbol1 as alias, symbol2} from \"filename\";\n\n.. index:: virtual filesystem, source unit name, import; path, filesystem path, import callback, Remix IDE\n\nImport Paths\n------------\n\nIn order to be able to support reproducible builds on all platforms, the Solidity compiler has to\nabstract away the details of the filesystem where source files are stored.\nFor this reason import paths do not refer directly to files in the host filesystem.\nInstead the compiler maintains an internal database (*virtual filesystem* or *VFS* for short) where\neach source unit is assigned a unique *source unit name* which is an opaque and unstructured identifier.\nThe import path specified in an import statement is translated into a source unit name and used to\nfind the corresponding source unit in this database.\n\nUsing the :ref:`Standard JSON ` API it is possible to directly provide the names and\ncontent of all the source files as a part of the compiler input.\nIn this case source unit names are truly arbitrary.\nIf, however, you want the compiler to automatically find and load source code into the VFS, your\nsource unit names need to be structured in a way that makes it possible for an :ref:`import callback\n` to locate them.\nWhen using the command-line compiler the default import callback supports only loading source code\nfrom the host filesystem, which means that your source unit names must be paths.\nSome environments provide custom callbacks that are more versatile.\nFor example the `Remix IDE `_ provides one that\nlets you `import files from HTTP, IPFS and Swarm URLs or refer directly to packages in NPM registry\n`_.\n\nFor a complete description of the virtual filesystem and the path resolution logic used by the\ncompiler see :ref:`Path Resolution `.\n\n.. index:: ! comment, natspec\n\nComments\n========\n\nSingle-line comments (``//``) and multi-line comments (``/*...*/``) are possible.\n\n.. code-block:: solidity\n\n // This is a single-line comment.\n\n /*\n This is a\n multi-line comment.\n */\n\n.. note::\n A single-line comment is terminated by any unicode line terminator\n (LF, VF, FF, CR, NEL, LS or PS) in UTF-8 encoding. The terminator is still part of\n the source code after the comment, so if it is not an ASCII symbol\n (these are NEL, LS and PS), it will lead to a parser error.\n\nAdditionally, there is another type of comment called a NatSpec comment,\nwhich is detailed in the :ref:`style guide`. They are written with a\ntriple slash (``///``) or a double asterisk block (``/** ... */``) and\nthey should be used directly above function declarations or statements.\n" }, { "path": "docs/make.bat", "content": "@ECHO OFF\n\nREM Command file for Sphinx documentation\n\nif \"%SPHINXBUILD%\" == \"\" (\n\tset SPHINXBUILD=sphinx-build\n)\nset BUILDDIR=_build\nset ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .\nset I18NSPHINXOPTS=%SPHINXOPTS% .\nif NOT \"%PAPER%\" == \"\" (\n\tset ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%\n\tset I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%\n)\n\nif \"%1\" == \"\" goto help\n\nif \"%1\" == \"help\" (\n\t:help\n\techo.Please use `make ^` where ^ is one of\n\techo. html to make standalone HTML files\n\techo. dirhtml to make HTML files named index.html in directories\n\techo. singlehtml to make a single large HTML file\n\techo. pickle to make pickle files\n\techo. json to make JSON files\n\techo. htmlhelp to make HTML files and a HTML help project\n\techo. qthelp to make HTML files and a qthelp project\n\techo. devhelp to make HTML files and a Devhelp project\n\techo. epub to make an epub\n\techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter\n\techo. latexpdf to make LaTeX files and run them through pdflatex\n\techo. text to make text files\n\techo. man to make manual pages\n\techo. texinfo to make Texinfo files\n\techo. gettext to make PO message catalogs\n\techo. changes to make an overview over all changed/added/deprecated items\n\techo. xml to make Docutils-native XML files\n\techo. pseudoxml to make pseudoxml-XML files for display purposes\n\techo. linkcheck to check all external links for integrity\n\techo. doctest to run all doctests embedded in the documentation if enabled\n\tgoto end\n)\n\nif \"%1\" == \"clean\" (\n\tfor /d %%i in (%BUILDDIR%\\*) do rmdir /q /s %%i\n\tdel /q /s %BUILDDIR%\\*\n\tgoto end\n)\n\n\n%SPHINXBUILD% 2> nul\nif errorlevel 9009 (\n\techo.\n\techo.The 'sphinx-build' command was not found. Make sure you have Sphinx\n\techo.installed, then set the SPHINXBUILD environment variable to point\n\techo.to the full path of the 'sphinx-build' executable. Alternatively you\n\techo.may add the Sphinx directory to PATH.\n\techo.\n\techo.If you don't have Sphinx installed, grab it from\n\techo.http://sphinx-doc.org/\n\texit /b 1\n)\n\nif \"%1\" == \"html\" (\n\t%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The HTML pages are in %BUILDDIR%/html.\n\tgoto end\n)\n\nif \"%1\" == \"dirhtml\" (\n\t%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.\n\tgoto end\n)\n\nif \"%1\" == \"singlehtml\" (\n\t%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.\n\tgoto end\n)\n\nif \"%1\" == \"pickle\" (\n\t%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished; now you can process the pickle files.\n\tgoto end\n)\n\nif \"%1\" == \"json\" (\n\t%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished; now you can process the JSON files.\n\tgoto end\n)\n\nif \"%1\" == \"htmlhelp\" (\n\t%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished; now you can run HTML Help Workshop with the ^\n.hhp project file in %BUILDDIR%/htmlhelp.\n\tgoto end\n)\n\nif \"%1\" == \"qthelp\" (\n\t%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished; now you can run \"qcollectiongenerator\" with the ^\n.qhcp project file in %BUILDDIR%/qthelp, like this:\n\techo.^> qcollectiongenerator %BUILDDIR%\\qthelp\\Solidity.qhcp\n\techo.To view the help file:\n\techo.^> assistant -collectionFile %BUILDDIR%\\qthelp\\Solidity.ghc\n\tgoto end\n)\n\nif \"%1\" == \"devhelp\" (\n\t%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished.\n\tgoto end\n)\n\nif \"%1\" == \"epub\" (\n\t%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The epub file is in %BUILDDIR%/epub.\n\tgoto end\n)\n\nif \"%1\" == \"latex\" (\n\t%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished; the LaTeX files are in %BUILDDIR%/latex.\n\tgoto end\n)\n\nif \"%1\" == \"latexpdf\" (\n\t%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex\n\tcd %BUILDDIR%/latex\n\tmake all-pdf\n\tcd %BUILDDIR%/..\n\techo.\n\techo.Build finished; the PDF files are in %BUILDDIR%/latex.\n\tgoto end\n)\n\nif \"%1\" == \"text\" (\n\t%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The text files are in %BUILDDIR%/text.\n\tgoto end\n)\n\nif \"%1\" == \"man\" (\n\t%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The manual pages are in %BUILDDIR%/man.\n\tgoto end\n)\n\nif \"%1\" == \"texinfo\" (\n\t%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.\n\tgoto end\n)\n\nif \"%1\" == \"gettext\" (\n\t%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The message catalogs are in %BUILDDIR%/locale.\n\tgoto end\n)\n\nif \"%1\" == \"changes\" (\n\t%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.The overview file is in %BUILDDIR%/changes.\n\tgoto end\n)\n\nif \"%1\" == \"linkcheck\" (\n\t%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Link check complete; look for any errors in the above output ^\nor in %BUILDDIR%/linkcheck/output.txt.\n\tgoto end\n)\n\nif \"%1\" == \"doctest\" (\n\t%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Testing of doctests in the sources finished, look at the ^\nresults in %BUILDDIR%/doctest/output.txt.\n\tgoto end\n)\n\nif \"%1\" == \"xml\" (\n\t%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The XML files are in %BUILDDIR%/xml.\n\tgoto end\n)\n\nif \"%1\" == \"pseudoxml\" (\n\t%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml\n\tif errorlevel 1 exit /b 1\n\techo.\n\techo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.\n\tgoto end\n)\n\n:end\n" }, { "path": "docs/metadata.rst", "content": ".. _metadata:\n\n#################\nContract Metadata\n#################\n\n.. index:: metadata, contract verification\n\nThe Solidity compiler automatically generates a JSON file.\nThe file contains two kinds of information about the compiled contract:\n\n- How to interact with the contract: ABI, and NatSpec documentation.\n- How to reproduce the compilation and verify a deployed contract:\n compiler version, compiler settings, and source files used.\n\nThe compiler appends by default the IPFS hash of the metadata file to the end\nof the runtime bytecode (not necessarily the creation bytecode) of each contract,\nso that, if published, you can retrieve the file in an authenticated way without\nhaving to resort to a centralized data provider. The other available options are\nthe Swarm hash and not appending the metadata hash to the bytecode. These can be\nconfigured via the :ref:`Standard JSON Interface`.\n\nYou have to publish the metadata file to IPFS, Swarm, or another service so\nthat others can access it. You create the file by using the ``solc --metadata``\ncommand together with the ``--output-dir`` parameter. Without the parameter,\nthe metadata will be written to standard output.\nThe metadata contains IPFS and Swarm references to the source code, so you have to\nupload all source files in addition to the metadata file. For IPFS, the hash contained\nin the CID returned by ``ipfs add`` (not the direct sha2-256 hash of the file)\nshall match with the one contained in the bytecode.\n\nThe metadata file has the following format. The example below is presented in a\nhuman-readable way. Properly formatted metadata should use quotes correctly,\nreduce whitespace to a minimum, and sort the keys of all objects in alphabetical order\nto arrive at a canonical formatting. Comments are not permitted and are used here only for\nexplanatory purposes.\n\n.. code-block:: javascript\n\n {\n // Required: Details about the compiler, contents are specific\n // to the language.\n \"compiler\": {\n // Optional: Hash of the compiler binary which produced this output\n \"keccak256\": \"0x123...\",\n // Required for Solidity: Version of the compiler\n \"version\": \"0.8.2+commit.661d1103\"\n },\n // Required: Source code language, basically selects a \"sub-version\"\n // of the specification\n \"language\": \"Solidity\",\n // Required: Generated information about the contract.\n \"output\": {\n // Required: ABI definition of the contract. See \"Contract ABI Specification\"\n \"abi\": [/* ... */],\n // Required: NatSpec developer documentation of the contract. See https://docs.soliditylang.org/en/latest/natspec-format.html for details.\n \"devdoc\": {\n // Contents of the @author NatSpec field of the contract\n \"author\": \"John Doe\",\n // Contents of the @dev NatSpec field of the contract\n \"details\": \"Interface of the ERC20 standard as defined in the EIP. See https://eips.ethereum.org/EIPS/eip-20 for details\",\n \"errors\": {\n \"MintToZeroAddress()\" : {\n \"details\": \"Cannot mint to zero address\"\n }\n },\n \"events\": {\n \"Transfer(address,address,uint256)\": {\n \"details\": \"Emitted when `value` tokens are moved from one account (`from`) toanother (`to`).\",\n \"params\": {\n \"from\": \"The sender address\",\n \"to\": \"The receiver address\",\n \"value\": \"The token amount\"\n }\n }\n },\n \"kind\": \"dev\",\n \"methods\": {\n \"transfer(address,uint256)\": {\n // Contents of the @dev NatSpec field of the method\n \"details\": \"Returns a boolean value indicating whether the operation succeeded. Must be called by the token holder address\",\n // Contents of the @param NatSpec fields of the method\n \"params\": {\n \"_value\": \"The amount tokens to be transferred\",\n \"_to\": \"The receiver address\"\n },\n // Contents of the @return NatSpec field.\n \"returns\": {\n // Return var name (here \"success\") if exists. \"_0\" as key if return var is unnamed\n \"success\": \"a boolean value indicating whether the operation succeeded\"\n }\n }\n },\n \"stateVariables\": {\n \"owner\": {\n // Contents of the @dev NatSpec field of the state variable\n \"details\": \"Must be set during contract creation. Can then only be changed by the owner\"\n }\n },\n // Contents of the @title NatSpec field of the contract\n \"title\": \"MyERC20: an example ERC20\",\n \"version\": 1 // NatSpec version\n },\n // Required: NatSpec user documentation of the contract. See \"NatSpec Format\"\n \"userdoc\": {\n \"errors\": {\n \"ApprovalCallerNotOwnerNorApproved()\": [\n {\n \"notice\": \"The caller must own the token or be an approved operator.\"\n }\n ]\n },\n \"events\": {\n \"Transfer(address,address,uint256)\": {\n \"notice\": \"`_value` tokens have been moved from `from` to `to`\"\n }\n },\n \"kind\": \"user\",\n \"methods\": {\n \"transfer(address,uint256)\": {\n \"notice\": \"Transfers `_value` tokens to address `_to`\"\n }\n },\n \"version\": 1 // NatSpec version\n }\n },\n // Required: Compiler settings.\n // Reflects the settings in the JSON input during compilation, except:\n // - Different format: \"libraries\" field\n // - Added field in metadata.settings: \"compilationTarget\"\n // - Not in metadata.settings: \"stopAfter\", \"debug.debugInfo\", \"outputSelection\"\n // See the standard JSON input's \"settings\" field docs for the rest.\n \"settings\": {\n // Required for Solidity: File path and the name of the contract or library this\n // metadata is created for. This field is not present in the standard JSON input settings.\n \"compilationTarget\": {\n \"myDirectory/myFile.sol\": \"MyContract\"\n },\n // Optional (false if omitted): Indicates whether experimental mode has been enabled.\n // Always matches the value of the `experimental` flag in CBOR metadata.\n // Note that experimental mode being enabled does not necessarily mean that any\n // experimental features were actually used, or if they were, that those features\n // affected the bytecode.\n \"experimental\": true,\n // Required for Solidity: Addresses for libraries used.\n // Note that metadata has a different format for \"libraries\" field than the standard JSON input.\n // metadata format = { \"MyLib.sol:MyLib\": \"0x123123...\" }\n // standard JSON input format = { \"MyLib.sol\": { \"MyLib\": \"0x123123...\" } }\n \"libraries\": {\n \"MyLib.sol:MyLib\": \"0x123123...\"\n },\n // ...\n // ...\n // ...\n // The rest of the fields and their defaults same as in std JSON input.\n },\n // Required: Compilation source files/source units, keys are file paths\n \"sources\": {\n \"settable\": {\n // Required (unless \"url\" is used): literal contents of the source file\n \"content\": \"contract settable is owned { uint256 private x = 0; function set(uint256 _x) public { if (msg.sender == owner) x = _x; } }\",\n // Required: keccak256 hash of the source file\n \"keccak256\": \"0x234...\"\n },\n \"myDirectory/myFile.sol\": {\n // Required: keccak256 hash of the source file\n \"keccak256\": \"0x123...\",\n // Optional: SPDX license identifier as given in the source file\n \"license\": \"MIT\",\n // Required (unless \"content\" is used, see above): Sorted URL(s)\n // to the source file, protocol is more or less arbitrary, but an\n // IPFS URL is recommended\n \"urls\": [ \"bzz-raw://7d7a...\", \"dweb:/ipfs/QmN...\" ]\n }\n },\n // Required: The version of the metadata format\n \"version\": 1\n }\n\n.. warning::\n Since the bytecode of the resulting contract contains the metadata hash by default, any\n change to the metadata might result in a change of the bytecode. This includes\n changes to a filename or path, and since the metadata includes a hash of all the\n sources used, a single whitespace change results in different metadata, and\n different bytecode.\n\n.. note::\n The ABI definition above has no fixed order. It can change with compiler versions.\n Starting from Solidity version 0.5.12, though, the array maintains a certain\n order.\n\n.. _encoding-of-the-metadata-hash-in-the-bytecode:\n\nEncoding of the Metadata Hash in the Bytecode\n=============================================\n\nThe compiler currently by default appends the\n`IPFS hash (in CID v0) `_\nof the canonical metadata file and the compiler version to the end of the bytecode.\nOptionally, a Swarm hash instead of the IPFS, or an experimental flag is used.\nBelow are all the possible fields:\n\n.. code-block:: javascript\n\n {\n // Present if \"bytecodeHash\" was \"ipfs\" in compiler settings\n \"ipfs\": \"\",\n // Present if \"bytecodeHash\" was \"bzzr1\" in compiler settings\n \"bzzr1\": \"\",\n // Previous versions were using \"bzzr0\" instead of \"bzzr1\"\n \"bzzr0\": \"\",\n // Present if experimental mode has been enabled either via \"--experimental\" flag or\n // \"settings.experimental\" option in Standard JSON\n \"experimental\": true,\n \"solc\": \"\"\n }\n\nBecause we might support other ways to retrieve the\nmetadata file in the future, this information is stored\n`CBOR `_-encoded. The last two bytes in the bytecode\nindicate the length of the CBOR encoded information. By looking at this length, the\nrelevant part of the bytecode can be decoded with a CBOR decoder.\n\nCheck the `Metadata Playground `_ to see it in action.\n\nWhereas release builds of solc use a 3 byte encoding of the version as shown\nabove (one byte each for major, minor and patch version number), pre-release builds\nwill instead use a complete version string including commit hash and build date.\n\nThe commandline flag ``--no-cbor-metadata`` can be used to skip metadata\nfrom getting appended at the end of the deployed bytecode. Equivalently, the\nboolean field ``settings.metadata.appendCBOR`` in Standard JSON input can be set to false.\n\n.. note::\n The CBOR mapping can also contain other keys, so it is better to fully\n decode the data by looking at the end of the bytecode for the CBOR length,\n and to use a proper CBOR parser. Do not rely on it starting with ``0xa264``\n or ``0xa2 0x64 'i' 'p' 'f' 's'``.\n\nUsage for Automatic Interface Generation and NatSpec\n====================================================\n\nThe metadata is used in the following way: A component that wants to interact\nwith a contract (e.g. a wallet) retrieves the code of the contract.\nIt decodes the CBOR encoded section containing the IPFS/Swarm hash of the\nmetadata file. With that hash, the metadata file is retrieved. That file\nis JSON-decoded into a structure like above.\n\nThe component can then use the ABI to automatically generate a rudimentary\nuser interface for the contract.\n\nFurthermore, the wallet can use the NatSpec user documentation to display a\nhuman-readable confirmation message to the user whenever they interact with\nthe contract, together with requesting authorization for the transaction signature.\n\nFor additional information, read :doc:`Ethereum Natural Language Specification (NatSpec) format `.\n\nUsage for Source Code Verification\n==================================\n\nIf pinned/published, it is possible to retrieve the metadata of the contract from IPFS/Swarm.\nThe metadata file also contains the URLs or the IPFS hashes of the source files, as well as\nthe compilation settings, i.e. everything needed to reproduce a compilation.\n\nWith this information it is then possible to verify the source code of a contract by\nreproducing the compilation, and comparing the bytecode from the compilation with\nthe bytecode of the deployed contract.\n\nThis automatically verifies the metadata since its hash is part of the bytecode, as well\nas the source codes, because their hashes are part of the metadata. Any change in the files\nor settings would result in a different metadata hash. The metadata here serves\nas a fingerprint of the whole compilation.\n\n`Sourcify `_ makes use of this feature for \"full/perfect verification\",\nas well as pinning the files publicly on IPFS to be accessed with the metadata hash.\n" }, { "path": "docs/natspec-format.rst", "content": ".. _natspec:\n\n##############\nNatSpec Format\n##############\n\nSolidity contracts can use a special form of comments to provide rich\ndocumentation for functions, return variables and more. This special form is\nnamed the Ethereum Natural Language Specification Format (NatSpec).\n\n.. note::\n\n NatSpec was inspired by `Doxygen `_.\n While it uses Doxygen-style comments and tags, there is no intention to keep\n strict compatibility with Doxygen. Please carefully examine the supported tags\n listed below.\n\nThis documentation is segmented into developer-focused messages and end-user-facing\nmessages. These messages may be shown to the end user (the human) at the\ntime that they will interact with the contract (i.e. sign a transaction).\n\nIt is recommended that Solidity contracts are fully annotated using NatSpec for\nall public interfaces (everything in the ABI).\n\nNatSpec includes the formatting for comments that the smart contract author will\nuse, and which are understood by the Solidity compiler. Also detailed below is\noutput of the Solidity compiler, which extracts these comments into a machine-readable\nformat.\n\nNatSpec may also include annotations used by third-party tools. These are most likely\naccomplished via the ``@custom:`` tag, and a good use case is analysis and verification\ntools.\n\n.. _header-doc-example:\n\nDocumentation Example\n=====================\n\nDocumentation is inserted above each ``contract``, ``interface``, ``library``,\n``function``, ``enum``, ``enum`` value and ``event`` using the Doxygen notation format.\nA ``public`` state variable is equivalent to a ``function``\nfor the purposes of NatSpec.\n\n- For Solidity you may choose ``///`` for single or multi-line\n comments, or ``/**`` and ending with ``*/``.\n\n- For Vyper, use ``\"\"\"`` indented to the inner contents with bare\n comments. See the `Vyper\n documentation `__.\n\nThe following example shows a contract and a function using all available tags.\n\n.. note::\n\n The Solidity compiler only interprets tags if they are external or\n public. You are welcome to use similar comments for your internal and\n private functions, but those will not be parsed.\n\n This may change in the future.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.2 < 0.9.0;\n\n /// @title A simulator for trees\n /// @author Larry A. Gardner\n /// @notice You can use this contract for only the most basic simulation\n /// @dev All function calls are currently implemented without side effects\n /// @custom:experimental This is an experimental contract.\n contract Tree {\n /// @notice Calculate tree age in years, rounded up, for live trees\n /// @dev The Alexandr N. Tetearing algorithm could increase precision\n /// @param rings The number of rings from dendrochronological sample\n /// @return Age in years, rounded up for partial years\n /// @return Name of the tree\n function age(uint256 rings) external virtual pure returns (uint256, string memory) {\n return (rings + 1, \"tree\");\n }\n\n /// @notice Returns the amount of leaves the tree has.\n /// @dev Returns only a fixed number.\n function leaves() external virtual pure returns(uint256) {\n return 2;\n }\n }\n\n contract Plant {\n function leaves() external virtual pure returns(uint256) {\n return 3;\n }\n }\n\n contract KumquatTree is Tree, Plant {\n function age(uint256 rings) external override pure returns (uint256, string memory) {\n return (rings + 2, \"Kumquat\");\n }\n\n /// Return the amount of leaves that this specific kind of tree has\n /// @inheritdoc Tree\n function leaves() external override(Tree, Plant) pure returns(uint256) {\n return 3;\n }\n }\n\n.. _header-tags:\n\nTags\n====\n\nAll tags are optional. The following table explains the purpose of each\nNatSpec tag and where it may be used. As a special case, if no tags are\nused then the Solidity compiler will interpret a ``///`` or ``/**`` comment\nin the same way as if it were tagged with ``@notice``.\n\n=============== ====================================================================================== =============================\nTag Context\n=============== ====================================================================================== =============================\n``@title`` A title that should describe the contract/interface contract, library, interface, struct, enum, enum values\n``@author`` The name of the author contract, library, interface, struct, enum, enum values\n``@notice`` Explain to an end user what this does contract, library, interface, function, public state variable, event, struct, enum, enum values error\n``@dev`` Explain to a developer any extra details contract, library, interface, function, state variable, event, struct, enum, enum values, error\n``@param`` Documents a parameter just like in Doxygen (must be followed by parameter name) function, event, enum values, error\n``@return`` Documents the return variables of a contract's function function, enum, enum values, public state variable\n``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, enum, enum values, public state variable\n``@custom:...`` Custom tag, semantics is application-defined everywhere\n=============== ====================================================================================== =============================\n\nIf your function returns multiple values, like ``(int quotient, int remainder)``\nthen use multiple ``@return`` statements in the same format as the ``@param`` statements.\n\nCustom tags start with ``@custom:`` and must be followed by one or more lowercase letters or hyphens.\nIt cannot start with a hyphen however. They can be used everywhere and are part of the developer documentation.\n\n.. _header-dynamic:\n\nDynamic expressions\n-------------------\n\nThe Solidity compiler will pass through NatSpec documentation from your Solidity\nsource code to the JSON output as described in this guide. The consumer of this\nJSON output, for example the end-user client software, may present this to the end-user directly or it may apply some pre-processing.\n\nFor example, some client software will render:\n\n.. code:: Solidity\n\n /// @notice This function will multiply `a` by 7\n\nto the end-user as:\n\n.. code:: text\n\n This function will multiply 10 by 7\n\nif a function is being called and the input ``a`` is assigned a value of 10.\n\n.. _header-inheritance:\n\nInheritance Notes\n-----------------\n\nFunctions without NatSpec will automatically inherit the documentation of their\nbase function. Exceptions to this are:\n\n* When the parameter names are different.\n* When there is more than one base function.\n* When there is an explicit ``@inheritdoc`` tag which specifies which contract should be used to inherit.\n\n.. _header-output:\n\nDocumentation Output\n====================\n\nWhen parsed by the compiler, documentation such as the one from the\nabove example will produce two different JSON files. One is meant to be\nconsumed by the end user as a notice when a function is executed and the\nother to be used by the developer.\n\nIf the above contract is saved as ``ex1.sol`` then you can generate the\ndocumentation using:\n\n.. code-block:: shell\n\n solc --userdoc --devdoc ex1.sol\n\nAnd the output is below.\n\n.. note::\n Starting Solidity version 0.6.11 the NatSpec output also contains a ``version`` and a ``kind`` field.\n Currently the ``version`` is set to ``1`` and ``kind`` must be one of ``user`` or ``dev``.\n In the future it is possible that new versions will be introduced, deprecating older ones.\n\n.. _header-user-doc:\n\nUser Documentation\n------------------\n\nThe above documentation will produce the following user documentation\nJSON file as output for the ``Tree`` contract:\n\n.. code-block:: json\n\n {\n \"version\" : 1,\n \"kind\" : \"user\",\n \"methods\" :\n {\n \"age(uint256)\" :\n {\n \"notice\" : \"Calculate tree age in years, rounded up, for live trees\"\n },\n \"leaves()\" :\n {\n \"notice\" : \"Returns the amount of leaves the tree has.\"\n }\n },\n \"notice\" : \"You can use this contract for only the most basic simulation\"\n }\n\nNote that the key by which to find the methods is the function's\ncanonical signature as defined in the :ref:`Contract\nABI ` and not simply the function's\nname.\n\n.. _header-developer-doc:\n\nDeveloper Documentation\n-----------------------\n\nApart from the user documentation file, a developer documentation JSON\nfile should also be produced and should look like this:\n\n.. code-block:: json\n\n {\n \"version\" : 1,\n \"kind\" : \"dev\",\n \"author\" : \"Larry A. Gardner\",\n \"details\" : \"All function calls are currently implemented without side effects\",\n \"custom:experimental\" : \"This is an experimental contract.\",\n \"methods\" :\n {\n \"age(uint256)\" :\n {\n \"details\" : \"The Alexandr N. Tetearing algorithm could increase precision\",\n \"params\" :\n {\n \"rings\" : \"The number of rings from dendrochronological sample\"\n },\n \"returns\" : {\n \"_0\" : \"Age in years, rounded up for partial years\",\n \"_1\" : \"Name of the tree\"\n }\n },\n \"leaves()\" :\n {\n \"details\" : \"Returns only a fixed number.\"\n }\n },\n \"title\" : \"A simulator for trees\"\n }\n" }, { "path": "docs/path-resolution.rst", "content": ".. _path-resolution:\n\n**********************\nImport Path Resolution\n**********************\n\nIn order to be able to support reproducible builds on all platforms, the Solidity compiler has to\nabstract away the details of the filesystem where source files are stored.\nPaths used in imports must work the same way everywhere while the command-line interface must be\nable to work with platform-specific paths to provide good user experience.\nThis section aims to explain in detail how Solidity reconciles these requirements.\n\n.. index:: ! virtual filesystem, ! VFS, ! source unit name\n.. _virtual-filesystem:\n\nVirtual Filesystem\n==================\n\nThe compiler maintains an internal database (*virtual filesystem* or *VFS* for short) where each\nsource unit is assigned a unique *source unit name* which is an opaque and unstructured identifier.\nWhen you use the :ref:`import statement `, you specify an *import path* that references a\nsource unit name.\n\n.. index:: ! import callback, ! Host Filesystem Loader, ! --no-import-callback\n.. _import-callback:\n\nImport Callback\n---------------\n\nThe VFS is initially populated only with files the compiler has received as input.\nAdditional files can be loaded during compilation using an *import callback*, which is different\ndepending on the type of compiler you use (see below).\nIf the compiler does not find any source unit name matching the import path in the VFS, it invokes\nthe callback, which is responsible for obtaining the source code to be placed under that name.\nAn import callback is free to interpret source unit names in an arbitrary way, not just as paths.\nIf there is no callback available when one is needed or if it fails to locate the source code,\ncompilation fails.\n\nBy default, the command-line compiler provides the *Host Filesystem Loader* - a rudimentary callback\nthat interprets a source unit name as a path in the local filesystem.\nThis callback can be disabled using the ``--no-import-callback`` command-line option.\nThe `JavaScript interface `_ does not provide any by default,\nbut one can be provided by the user.\nThis mechanism can be used to obtain source code from locations other than the local filesystem\n(which may not even be accessible, e.g. when the compiler is running in a browser).\nFor example the `Remix IDE `_ provides a versatile callback that\nlets you `import files from HTTP, IPFS and Swarm URLs or refer directly to packages in NPM registry\n`_.\n\n.. note::\n\n Host Filesystem Loader's file lookup is platform-dependent.\n For example backslashes in a source unit name can be interpreted as directory separators or not\n and the lookup can be case-sensitive or not, depending on the underlying platform.\n\n For portability it is recommended to avoid using import paths that will work correctly only\n with a specific import callback or only on one platform.\n For example you should always use forward slashes since they work as path separators also on\n platforms that support backslashes.\n\nInitial Content of the Virtual Filesystem\n-----------------------------------------\n\nThe initial content of the VFS depends on how you invoke the compiler:\n\n#. **solc / command-line interface**\n\n When you compile a file using the command-line interface of the compiler, you provide one or\n more paths to files containing Solidity code:\n\n .. code-block:: bash\n\n solc contract.sol /usr/local/dapp-bin/token.sol\n\n The source unit name of a file loaded this way is constructed by converting its path to a\n canonical form and, if possible, making it relative to either the base path or one of the\n include paths.\n See :ref:`CLI Path Normalization and Stripping ` for\n a detailed description of this process.\n\n .. index:: standard JSON\n\n#. **Standard JSON**\n\n When using the :ref:`Standard JSON ` API (via either the `JavaScript interface\n `_ or the ``--standard-json`` command-line option)\n you provide input in JSON format, containing, among other things, the content of all your source\n files:\n\n .. code-block:: json\n\n {\n \"language\": \"Solidity\",\n \"sources\": {\n \"contract.sol\": {\n \"content\": \"import \\\"./util.sol\\\";\\ncontract C {}\"\n },\n \"util.sol\": {\n \"content\": \"library Util {}\"\n },\n \"/usr/local/dapp-bin/token.sol\": {\n \"content\": \"contract Token {}\"\n }\n },\n \"settings\": {\"outputSelection\": {\"*\": { \"*\": [\"metadata\", \"evm.bytecode\"]}}}\n }\n\n The ``sources`` dictionary becomes the initial content of the virtual filesystem and its keys\n are used as source unit names.\n\n .. _initial-vfs-content-standard-json-with-import-callback:\n\n#. **Standard JSON (via import callback)**\n\n With Standard JSON it is also possible to tell the compiler to use the import callback to obtain\n the source code:\n\n .. code-block:: json\n\n {\n \"language\": \"Solidity\",\n \"sources\": {\n \"/usr/local/dapp-bin/token.sol\": {\n \"urls\": [\n \"/projects/mytoken.sol\",\n \"https://example.com/projects/mytoken.sol\"\n ]\n }\n },\n \"settings\": {\"outputSelection\": {\"*\": { \"*\": [\"metadata\", \"evm.bytecode\"]}}}\n }\n\n If an import callback is available, the compiler will give it the strings specified in\n ``urls`` one by one, until one is loaded successfully or the end of the list is reached.\n\n The source unit names are determined the same way as when using ``content`` - they are keys of\n the ``sources`` dictionary and the content of ``urls`` does not affect them in any way.\n\n .. index:: standard input, stdin, \n\n#. **Standard input**\n\n On the command-line it is also possible to provide the source by sending it to compiler's\n standard input:\n\n .. code-block:: bash\n\n echo 'import \"./util.sol\"; contract C {}' | solc -\n\n ``-`` used as one of the arguments instructs the compiler to place the content of the standard\n input in the virtual filesystem under a special source unit name: ````.\n\nOnce the VFS is initialized, additional files can still be added to it only through the import\ncallback.\n\n.. index:: ! import; path\n\nImports\n=======\n\nThe import statement specifies an *import path*.\nBased on how the import path is specified, we can divide imports into two categories:\n\n- :ref:`Direct imports `, where you specify the full source unit name directly.\n- :ref:`Relative imports `, where you specify a path starting with ``./`` or ``../``\n to be combined with the source unit name of the importing file.\n\n\n.. code-block:: solidity\n :caption: contracts/contract.sol\n\n import \"./math/math.sol\";\n import \"contracts/tokens/token.sol\";\n\nIn the above ``./math/math.sol`` and ``contracts/tokens/token.sol`` are import paths while the\nsource unit names they translate to are ``contracts/math/math.sol`` and ``contracts/tokens/token.sol``\nrespectively.\n\n.. index:: ! direct import, import; direct\n.. _direct-imports:\n\nDirect Imports\n--------------\n\nAn import that does not start with ``./`` or ``../`` is a *direct import*.\n\n.. code-block:: solidity\n\n import \"/project/lib/util.sol\"; // source unit name: /project/lib/util.sol\n import \"lib/util.sol\"; // source unit name: lib/util.sol\n import \"@openzeppelin/address.sol\"; // source unit name: @openzeppelin/address.sol\n import \"https://example.com/token.sol\"; // source unit name: https://example.com/token.sol\n\nAfter applying any :ref:`import remappings ` the import path simply becomes the\nsource unit name.\n\n.. note::\n\n A source unit name is just an identifier and even if its value happens to look like a path, it\n is not subject to the normalization rules you would typically expect in a shell.\n Any ``/./`` or ``/../`` segments or sequences of multiple slashes remain a part of it.\n When the source is provided via Standard JSON interface it is entirely possible to associate\n different content with source unit names that would refer to the same file on disk.\n\nWhen the source is not available in the virtual filesystem, the compiler passes the source unit name\nto the import callback.\nThe Host Filesystem Loader will attempt to use it as a path and look up the file on disk.\nAt this point the platform-specific normalization rules kick in and names that were considered\ndifferent in the VFS may actually result in the same file being loaded.\nFor example ``/project/lib/math.sol`` and ``/project/lib/../lib///math.sol`` are considered\ncompletely different in the VFS even though they refer to the same file on disk.\n\n.. note::\n\n Even if an import callback ends up loading source code for two different source unit names from\n the same file on disk, the compiler will still see them as separate source units.\n It is the source unit name that matters, not the physical location of the code.\n\n.. index:: ! relative import, ! import; relative\n.. _relative-imports:\n\nRelative Imports\n----------------\n\nAn import starting with ``./`` or ``../`` is a *relative import*.\nSuch imports specify a path relative to the source unit name of the importing source unit:\n\n.. code-block:: solidity\n :caption: /project/lib/math.sol\n\n import \"./util.sol\" as util; // source unit name: /project/lib/util.sol\n import \"../token.sol\" as token; // source unit name: /project/token.sol\n\n.. code-block:: solidity\n :caption: lib/math.sol\n\n import \"./util.sol\" as util; // source unit name: lib/util.sol\n import \"../token.sol\" as token; // source unit name: token.sol\n\n.. note::\n\n Relative imports **always** start with ``./`` or ``../`` so ``import \"util.sol\"``, unlike\n ``import \"./util.sol\"``, is a direct import.\n While both paths would be considered relative in the host filesystem, ``util.sol`` is actually\n absolute in the VFS.\n\nLet us define a *path segment* as any non-empty part of the path that does not contain a separator\nand is bounded by two path separators.\nA separator is a forward slash or the beginning/end of the string.\nFor example in ``./abc/..//`` there are three path segments: ``.``, ``abc`` and ``..``.\n\nThe compiler resolves the import into a source unit name based on the import path, in the following way:\n\n#. We start with the source unit name of the importing source unit.\n#. The last path segment with preceding slashes is removed from the resolved name.\n#. Then, for every segment in the import path, starting from the leftmost one:\n\n - If the segment is ``.``, it is skipped.\n - If the segment is ``..``, the last path segment with preceding slashes is removed from the resolved name.\n - Otherwise, the segment (preceded by a single slash if the resolved name is not empty), is appended to the resolved name.\n\nThe removal of the last path segment with preceding slashes is understood to\nwork as follows:\n\n1. Everything past the last slash is removed (i.e. ``a/b//c.sol`` becomes ``a/b//``).\n2. All trailing slashes are removed (i.e. ``a/b//`` becomes ``a/b``).\n\nNote that the process normalizes the part of the resolved source unit name that comes from the import path according\nto the usual rules for UNIX paths, i.e. all ``.`` and ``..`` are removed and multiple slashes are\nsquashed into a single one.\nOn the other hand, the part that comes from the source unit name of the importing module remains unnormalized.\nThis ensures that the ``protocol://`` part does not turn into ``protocol:/`` if the importing file\nis identified with a URL.\n\nIf your import paths are already normalized, you can expect the above algorithm to produce very\nintuitive results.\nHere are some examples of what you can expect if they are not:\n\n.. code-block:: solidity\n :caption: lib/src/../contract.sol\n\n import \"./util/./util.sol\"; // source unit name: lib/src/../util/util.sol\n import \"./util//util.sol\"; // source unit name: lib/src/../util/util.sol\n import \"../util/../array/util.sol\"; // source unit name: lib/src/array/util.sol\n import \"../.././../util.sol\"; // source unit name: util.sol\n import \"../../.././../util.sol\"; // source unit name: util.sol\n\n.. note::\n\n The use of relative imports containing leading ``..`` segments is not recommended.\n The same effect can be achieved in a more reliable way by using direct imports with\n :ref:`base path and include paths `.\n\n.. index:: ! base path, ! --base-path, ! include paths, ! --include-path\n.. _base-and-include-paths:\n\nBase Path and Include Paths\n===========================\n\nThe base path and include paths represent directories that the Host Filesystem Loader will load files from.\nWhen a source unit name is passed to the loader, it prepends the base path to it and performs a\nfilesystem lookup.\nIf the lookup does not succeed, the same is done with all directories on the include path list.\n\nIt is recommended to set the base path to the root directory of your project and use include paths to\nspecify additional locations that may contain libraries your project depends on.\nThis lets you import from these libraries in a uniform way, no matter where they are located in the\nfilesystem relative to your project.\nFor example, if you use npm to install packages and your contract imports\n``@openzeppelin/contracts/utils/Strings.sol``, you can use these options to tell the compiler that\nthe library can be found in one of the npm package directories:\n\n.. code-block:: bash\n\n solc contract.sol \\\n --base-path . \\\n --include-path node_modules/ \\\n --include-path /usr/local/lib/node_modules/\n\nYour contract will compile (with the same exact metadata) no matter whether you install the library\nin the local or global package directory or even directly under your project root.\n\nBy default the base path is empty, which leaves the source unit name unchanged.\nWhen the source unit name is a relative path, this results in the file being looked up in the\ndirectory the compiler has been invoked from.\nIt is also the only value that results in absolute paths in source unit names being actually\ninterpreted as absolute paths on disk.\nIf the base path itself is relative, it is interpreted as relative to the current working directory\nof the compiler.\n\n.. note::\n\n Include paths cannot have empty values and must be used together with a non-empty base path.\n\n.. note::\n\n Include paths and base path can overlap as long as it does not make import resolution ambiguous.\n For example, you can specify a directory inside base path as an include directory or have an\n include directory that is a subdirectory of another include directory.\n The compiler will only issue an error if the source unit name passed to the Host Filesystem\n Loader represents an existing path when combined with multiple include paths or an include path\n and base path.\n\n.. _cli-path-normalization-and-stripping:\n\nCLI Path Normalization and Stripping\n------------------------------------\n\nOn the command-line the compiler behaves just as you would expect from any other program:\nit accepts paths in a format native to the platform and relative paths are relative to the current\nworking directory.\nThe source unit names assigned to files whose paths are specified on the command-line, however,\nshould not change just because the project is being compiled on a different platform or because the\ncompiler happens to have been invoked from a different directory.\nTo achieve this, paths to source files coming from the command-line must be converted to a canonical\nform, and, if possible, made relative to the base path or one of the include paths.\n\nThe normalization rules are as follows:\n\n- If a path is relative, it is made absolute by prepending the current working directory to it.\n- Internal ``.`` and ``..`` segments are collapsed.\n- Platform-specific path separators are replaced with forward slashes.\n- Sequences of multiple consecutive path separators are squashed into a single separator (unless\n they are the leading slashes of an `UNC path `_).\n- If the path includes a root name (e.g. a drive letter on Windows) and the root is the same as the\n root of the current working directory, the root is replaced with ``/``.\n- Symbolic links in the path are **not** resolved.\n\n - The only exception is the path to the current working directory prepended to relative paths in\n the process of making them absolute.\n On some platforms the working directory is reported always with symbolic links resolved so for\n consistency the compiler resolves them everywhere.\n\n- The original case of the path is preserved even if the filesystem is case-insensitive but\n `case-preserving `_ and the actual case on\n disk is different.\n\n.. note::\n\n There are situations where paths cannot be made platform-independent.\n For example on Windows the compiler can avoid using drive letters by referring to the root\n directory of the current drive as ``/`` but drive letters are still necessary for paths leading\n to other drives.\n You can avoid such situations by ensuring that all the files are available within a single\n directory tree on the same drive.\n\nAfter normalization the compiler attempts to make the source file path relative.\nIt tries the base path first and then the include paths in the order they were given.\nIf the base path is empty or not specified, it is treated as if it was equal to the path to the\ncurrent working directory (with all symbolic links resolved).\nThe result is accepted only if the normalized directory path is the exact prefix of the normalized\nfile path.\nOtherwise the file path remains absolute.\nThis makes the conversion unambiguous and ensures that the relative path does not start with ``../``.\nThe resulting file path becomes the source unit name.\n\n.. note::\n\n The relative path produced by stripping must remain unique within the base path and include paths.\n For example the compiler will issue an error for the following command if both\n ``/project/contract.sol`` and ``/lib/contract.sol`` exist:\n\n .. code-block:: bash\n\n solc /project/contract.sol --base-path /project --include-path /lib\n\n.. note::\n\n Prior to version 0.8.8, CLI path stripping was not performed and the only normalization applied\n was the conversion of path separators.\n When working with older versions of the compiler it is recommended to invoke the compiler from\n the base path and to only use relative paths on the command-line.\n\n.. index:: ! allowed paths, ! --allow-paths, remapping; target\n.. _allowed-paths:\n\nAllowed Paths\n=============\n\nAs a security measure, the Host Filesystem Loader will refuse to load files from outside of a few\nlocations that are considered safe by default:\n\n- Outside of Standard JSON mode:\n\n - The directories containing input files listed on the command-line.\n - The directories used as :ref:`remapping ` targets.\n If the target is not a directory (i.e does not end with ``/``, ``/.`` or ``/..``) the directory\n containing the target is used instead.\n - Base path and include paths.\n\n- In Standard JSON mode:\n\n - Base path and include paths.\n\nAdditional directories can be whitelisted using the ``--allow-paths`` option.\nThe option accepts a comma-separated list of paths:\n\n.. code-block:: bash\n\n cd /home/user/project/\n solc token/contract.sol \\\n lib/util.sol=libs/util.sol \\\n --base-path=token/ \\\n --include-path=/lib/ \\\n --allow-paths=../utils/,/tmp/libraries\n\nWhen the compiler is invoked with the command shown above, the Host Filesystem Loader will allow\nimporting files from the following directories:\n\n- ``/home/user/project/token/`` (because ``token/`` contains the input file and also because it is\n the base path),\n- ``/lib/`` (because ``/lib/`` is one of the include paths),\n- ``/home/user/project/libs/`` (because ``libs/`` is a directory containing a remapping target),\n- ``/home/user/utils/`` (because of ``../utils/`` passed to ``--allow-paths``),\n- ``/tmp/libraries/`` (because of ``/tmp/libraries`` passed to ``--allow-paths``),\n\n.. note::\n\n The working directory of the compiler is one of the paths allowed by default only if it\n happens to be the base path (or the base path is not specified or has an empty value).\n\n.. note::\n\n The compiler does not check if allowed paths actually exist and whether they are directories.\n Non-existent or empty paths are simply ignored.\n If an allowed path matches a file rather than a directory, the file is considered whitelisted, too.\n\n.. note::\n\n Allowed paths are case-sensitive even if the filesystem is not.\n The case must exactly match the one used in your imports.\n For example ``--allow-paths tokens`` will not match ``import \"Tokens/IERC20.sol\"``.\n\n.. warning::\n\n Files and directories only reachable through symbolic links from allowed directories are not\n automatically whitelisted.\n For example if ``token/contract.sol`` in the example above was actually a symlink pointing at\n ``/etc/passwd`` the compiler would refuse to load it unless ``/etc/`` was one of the allowed\n paths too.\n\n.. index:: ! remapping; import, ! import; remapping, ! remapping; context, ! remapping; prefix, ! remapping; target\n.. _import-remapping:\n\nImport Remapping\n================\n\nImport remapping allows you to redirect imports to a different location in the virtual filesystem.\nThe mechanism works by changing the translation between import paths and source unit names.\nFor example you can set up a remapping so that any import from the virtual directory\n``github.com/ethereum/dapp-bin/library/`` would be seen as an import from ``dapp-bin/library/`` instead.\n\nYou can limit the scope of a remapping by specifying a *context*.\nThis allows creating remappings that apply only to imports located in a specific library or a specific file.\nWithout a context a remapping is applied to every matching import in all the files in the virtual\nfilesystem.\n\nImport remappings have the form of ``context:prefix=target``:\n\n- ``context`` must match the beginning of the source unit name of the file containing the import.\n- ``prefix`` must match the beginning of the source unit name resulting from the import.\n- ``target`` is the value the prefix is replaced with.\n\nFor example, if you clone https://github.com/ethereum/dapp-bin/ locally to ``/project/dapp-bin``\nand run the compiler with:\n\n.. code-block:: bash\n\n solc github.com/ethereum/dapp-bin/=dapp-bin/ --base-path /project source.sol\n\nyou can use the following in your source file:\n\n.. code-block:: solidity\n\n import \"github.com/ethereum/dapp-bin/library/math.sol\"; // source unit name: dapp-bin/library/math.sol\n\nThe compiler will look for the file in the VFS under ``dapp-bin/library/math.sol``.\nIf the file is not available there, the source unit name will be passed to the Host Filesystem\nLoader, which will then look in ``/project/dapp-bin/library/math.sol``.\n\n.. warning::\n\n Information about remappings is stored in contract metadata.\n Since the binary produced by the compiler has a hash of the metadata embedded in it, any\n modification to the remappings will result in different bytecode.\n\n For this reason you should be careful not to include any local information in remapping targets.\n For example if your library is located in ``/home/user/packages/mymath/math.sol``, a remapping\n like ``@math/=/home/user/packages/mymath/`` would result in your home directory being included in\n the metadata.\n To be able to reproduce the same bytecode with such a remapping on a different machine, you\n would need to recreate parts of your local directory structure in the VFS and (if you rely on\n Host Filesystem Loader) also in the host filesystem.\n\n To avoid having your local directory structure embedded in the metadata, it is recommended to\n designate the directories containing libraries as *include paths* instead.\n For example, in the example above ``--include-path /home/user/packages/`` would let you use\n imports starting with ``mymath/``.\n Unlike remapping, the option on its own will not make ``mymath`` appear as ``@math`` but this\n can be achieved by creating a symbolic link or renaming the package subdirectory.\n\nAs a more complex example, suppose you rely on a module that uses an old version of dapp-bin that\nyou checked out to ``/project/dapp-bin_old``, then you can run:\n\n.. code-block:: bash\n\n solc module1:github.com/ethereum/dapp-bin/=dapp-bin/ \\\n module2:github.com/ethereum/dapp-bin/=dapp-bin_old/ \\\n --base-path /project \\\n source.sol\n\nThis means that all imports in ``module2`` point to the old version but imports in ``module1``\npoint to the new version.\n\nHere are the detailed rules governing the behavior of remappings:\n\n#. **Remappings only affect the translation between import paths and source unit names.**\n\n Source unit names added to the VFS in any other way cannot be remapped.\n For example the paths you specify on the command-line and the ones in ``sources.urls`` in\n Standard JSON are not affected.\n\n .. code-block:: bash\n\n solc /project/=/contracts/ /project/contract.sol # source unit name: /project/contract.sol\n\n In the example above the compiler will load the source code from ``/project/contract.sol`` and\n place it under that exact source unit name in the VFS, not under ``/contract/contract.sol``.\n\n#. **Context and prefix must match source unit names, not import paths.**\n\n - This means that you cannot remap ``./`` or ``../`` directly since they are replaced during\n the translation to source unit name but you can remap the part of the name they are replaced\n with:\n\n .. code-block:: bash\n\n solc ./=a/ /project/=b/ /project/contract.sol # source unit name: /project/contract.sol\n\n .. code-block:: solidity\n :caption: /project/contract.sol\n\n import \"./util.sol\" as util; // source unit name: b/util.sol\n\n - You cannot remap base path or any other part of the path that is only added internally by an\n import callback:\n\n .. code-block:: bash\n\n solc /project/=/contracts/ /project/contract.sol --base-path /project # source unit name: contract.sol\n\n .. code-block:: solidity\n :caption: /project/contract.sol\n\n import \"util.sol\" as util; // source unit name: util.sol\n\n#. **Target is inserted directly into the source unit name and does not necessarily have to be a valid path.**\n\n - It can be anything as long as the import callback can handle it.\n In case of the Host Filesystem Loader this includes also relative paths.\n When using the JavaScript interface you can even use URLs and abstract identifiers if\n your callback can handle them.\n\n - Remapping happens after relative imports have already been resolved into source unit names.\n This means that targets starting with ``./`` and ``../`` have no special meaning and are\n relative to the base path rather than to the location of the source file.\n\n - Remapping targets are not normalized so ``@root/=./a/b//`` will remap ``@root/contract.sol``\n to ``./a/b//contract.sol`` and not ``a/b/contract.sol``.\n\n - If the target does not end with a slash, the compiler will not add one automatically:\n\n .. code-block:: bash\n\n solc /project/=/contracts /project/contract.sol # source unit name: /project/contract.sol\n\n .. code-block:: solidity\n :caption: /project/contract.sol\n\n import \"/project/util.sol\" as util; // source unit name: /contractsutil.sol\n\n#. **Context and prefix are patterns and matches must be exact.**\n\n - ``a//b=c`` will not match ``a/b``.\n - source unit names are not normalized so ``a/b=c`` will not match ``a//b`` either.\n - Parts of file and directory names can match as well.\n ``/newProject/con:/new=old`` will match ``/newProject/contract.sol`` and remap it to\n ``oldProject/contract.sol``.\n\n#. **At most one remapping is applied to a single import.**\n\n - If multiple remappings match the same source unit name, the one with the longest matching context is chosen.\n - If contexts are identical, the one with the longest matching prefix is chosen.\n - If contexts and prefixes are identical, the one specified last wins.\n - Remappings do not work on other remappings. For example ``a=b b=c c=d`` will not result in ``a``\n being remapped to ``d``.\n\n#. **Prefix cannot be empty but context and target are optional.**\n\n - If ``target`` is the empty string, ``prefix`` is simply removed from import paths.\n - Empty ``context`` means that the remapping applies to all imports in all source units.\n\n.. index:: Remix IDE, file://\n\nUsing URLs in imports\n=====================\n\nMost URL prefixes such as ``https://`` or ``data://`` have no special meaning in import paths.\nThe only exception is ``file://`` which is stripped from source unit names by the Host Filesystem\nLoader.\n\nWhen compiling locally you can use import remapping to replace the protocol and domain part with a\nlocal path:\n\n.. code-block:: bash\n\n solc :https://github.com/ethereum/dapp-bin=/usr/local/dapp-bin contract.sol\n\nNote the leading ``:``, which is necessary when the remapping context is empty.\nOtherwise the ``https:`` part would be interpreted by the compiler as the context.\n" }, { "path": "docs/requirements.txt", "content": "# Older versions of sphinx-rtd-theme do not work with never docutils but have a bug in the dependency\n# which could result in it being installed anyway and the style (especially bullet points) being broken.\n# See https://github.com/readthedocs/sphinx_rtd_theme/issues/1115\n# theme >=3.0.0 removes the display_version option in favor of version_selector and language_selector\n# Use rtd theme version that supports sphinx>=8.0\nsphinx_rtd_theme>=3.0.0\n\npygments-lexer-solidity>=0.7.0\nsphinx-syntax>=1.0.1\n\n# Sphinx version constraints for sphinx-syntax compatibility\nsphinx>=8.0.0, <9.0.0\n" }, { "path": "docs/resources.rst", "content": "#########\nResources\n#########\n\nGeneral Resources\n=================\n\n* `Ethereum.org Developers page `_\n* `Ethereum StackExchange `_\n* `Solidity website `_\n* `Solidity changelog `_\n* `Solidity codebase on GitHub `_\n* `Solidity language users chat `_\n* `Solidity compiler developers chat `_\n* `awesome-solidity `_\n* `Solidity by Example `_\n* `Solidity documentation community translations `_\n* `Solidity and Smart Contract Glossary `_\n\nIntegrated (Ethereum) Development Environments\n==============================================\n\n* `Ape `_\n A Python-based web3 development tool for compiling, testing, and interacting with smart contracts.\n\n* `Brownie `_\n A Python-based development and testing framework for smart contracts targeting the Ethereum Virtual Machine.\n 💡 Note: As per the official docs, Brownie is no longer actively maintained.\n Future releases may come sporadically - or never at all.\n Check out Ape Framework (first in list) for all your python Ethereum development needs.\n\n* `Dapp `_\n Tool for building, testing and deploying smart contracts from the command-line.\n\n* `Foundry `_\n Fast, portable and modular toolkit for Ethereum application development written in Rust.\n\n* `Hardhat `_\n Ethereum development environment with local Ethereum network, debugging features and plugin ecosystem.\n\n* `Remix `_\n Browser-based IDE with integrated compiler and Solidity runtime environment without server-side components.\n\n* `Truffle `_\n Ethereum development framework.\n 💡 Note: Consensys announced the sunset of Truffle on September 21, 2023.\n Current users may check out the migration path and available product support `here.\n `_\n\nEditor Integrations\n===================\n\n* Emacs\n\n * `Emacs Solidity `_\n Plugin for the Emacs editor providing syntax highlighting and compilation error reporting.\n\n* IntelliJ\n\n * `IntelliJ IDEA plugin `_\n Solidity plugin for IntelliJ IDEA (and all other JetBrains IDEs).\n\n* Sublime Text\n\n * `Package for SublimeText - Solidity language syntax `_\n Solidity syntax highlighting for SublimeText editor.\n\n* Vim\n\n * `Vim Solidity by Thesis `_\n Syntax highlighting for Solidity in Vim.\n\n * `Vim Solidity by TovarishFin `_\n Vim syntax file for Solidity.\n\n * `Vim Syntastic `_\n Plugin for the Vim editor providing compile checking.\n\n* Visual Studio Code (VS Code)\n\n * `Aderyn Visual Studio Code extension `_\n Solidity Smart contract analyzer designed to help find vulnerabilities. It supports projects built with Hardhat, Foundry, or any custom framework.\n\n * `Ethereum Remix Visual Studio Code extension `_\n Ethereum Remix extension pack for VS Code\n 💡 Note: As per the official repository, this extension has been removed from the VSCODE marketplace and will be replaced by a dedicated stand-alone desktop application.\n\n * `Solidity Visual Studio Code extension, by Juan Blanco `_\n Solidity plugin for Microsoft Visual Studio Code that includes syntax highlighting and the Solidity compiler.\n\n * `Solidity Visual Studio Code extension, by Nomic Foundation `_\n Solidity and Hardhat support by the Hardhat team, including: syntax highlighting, jump to definition, renames, quick fixes and inline solc warnings and errors.\n\n * `Solidity Visual Auditor extension `_\n Adds security centric syntax and semantic highlighting to Visual Studio Code.\n\n * `Truffle for VS Code `_\n Build, debug and deploy smart contracts on Ethereum and EVM-compatible blockchains.\n 💡 Note: This extension has built-in support for the Truffle Suite which is being sunset.\n For information on ongoing support, migration options and FAQs, visit the `Consensys blog.\n `_\n\nSolidity Tools\n==============\n\n* `ABI to Solidity interface converter `_\n A script for generating contract interfaces from the ABI of a smart contract.\n\n* `abi-to-sol `_\n Tool to generate Solidity interface source from a given ABI JSON.\n\n* `Aderyn `_\n Command Line Tool that helps find vulnerabilities in Solidity smart contracts. It supports projects built with Hardhat, Foundry, or any custom framework.\n\n* `Doxity `_\n Documentation Generator for Solidity.\n\n* `ethdebug `_\n A standard debugging data format for smart contracts on Ethereum-compatible networks.\n\n* `Ethlint `_\n Linter to identify and fix style and security issues in Solidity.\n\n* `evmdis `_\n EVM Disassembler that performs static analysis on the bytecode to provide a higher level of abstraction than raw EVM operations.\n\n* `EVM Lab `_\n A collection of tools to interact with the EVM. The package includes a VM, Etherchain API, and a trace-viewer with gas cost display.\n\n* `hevm `_\n EVM debugger and symbolic execution engine.\n\n* `leafleth `_\n A documentation generator for Solidity smart-contracts.\n\n* `Scaffold-ETH 2 `_\n Forkable Ethereum development stack focused on fast product iterations.\n\n* `Slippy `_\n A simple and powerful linter for Solidity.\n\n* `sol2uml `_\n Unified Modeling Language (UML) class diagram generator for Solidity contracts.\n\n* `solc-select `_\n A script to quickly switch between Solidity compiler versions.\n\n* `Solidity prettier plugin `_\n A Prettier Plugin for Solidity.\n\n* `Solidity REPL `_\n Try Solidity instantly with a command-line Solidity console.\n\n* `solgraph `_\n Visualize Solidity control flow and highlight potential security vulnerabilities.\n\n* `Solhint `_\n Solidity linter that provides security, style guide and best practice rules for smart contract validation.\n\n* `Sourcify `_\n Decentralized automated contract verification service and public repository of contract metadata.\n\n* `Sūrya `_\n Utility tool for smart contract systems, offering a number of visual outputs and information about the contracts' structure. Also supports querying the function call graph.\n\n* `Universal Mutator `_\n A tool for mutation generation, with configurable rules and support for Solidity and Vyper.\n\n* `Wake `_\n A Python-based Solidity development and testing framework with built-in vulnerability detectors.\n\nThird-Party Solidity Parsers and Grammars\n=========================================\n\n* `Solidity Parser for JavaScript `_\n A Solidity parser for JS built on top of a robust ANTLR4 grammar.\n" }, { "path": "docs/robots.txt.template", "content": "User-Agent: *\nSitemap: http://docs.soliditylang.org/sitemap.xml\nHost: docs.soliditylang.org\n\nAllow: /en/latest/\nAllow: /en/v0.7.6/\nAllow: /en/v{{ LATEST_VERSION }}/\nAllow: /_/downloads/en/latest/\nAllow: /_/downloads/en/0.7.6/\nAllow: /_/downloads/en/{{ LATEST_VERSION }}/\n\n# Prevent documentation for the development branches and older Solidity\n# versions from showing up in search results.\nDisallow: /en/*\nDisallow: /_/downloads/en/*\n" }, { "path": "docs/security-considerations.rst", "content": ".. _security_considerations:\n\n#######################\nSecurity Considerations\n#######################\n\nWhile it is usually quite easy to build software that works as expected,\nit is much harder to check that nobody can use it in a way that was **not** anticipated.\n\nIn Solidity, this is even more important because you can use smart contracts to handle tokens or,\npossibly, even more valuable things.\nFurthermore, every execution of a smart contract happens in public and,\nin addition to that, the source code is often available.\n\nOf course, you always have to consider how much is at stake:\nYou can compare a smart contract with a web service that is open to the public\n(and thus, also to malicious actors) and perhaps even open-source.\nIf you only store your grocery list on that web service, you might not have to take too much care,\nbut if you manage your bank account using that web service, you should be more careful.\n\nThis section will list some pitfalls and general security recommendations\nbut can, of course, never be complete.\nAlso, keep in mind that even if your smart contract code is bug-free,\nthe compiler or the platform itself might have a bug.\nA list of some publicly known security-relevant bugs of the compiler can be found\nin the :ref:`list of known bugs`, which is also machine-readable.\nNote that there is a `Bug Bounty Program `_\nthat covers the code generator of the Solidity compiler.\n\nAs always, with open-source documentation,\nplease help us extend this section (especially, some examples would not hurt)!\n\nNOTE: In addition to the list below, you can find more security recommendations and best practices\n`in Guy Lando's knowledge list `_ and\n`the Consensys GitHub repo `_.\n\n********\nPitfalls\n********\n\nPrivate Information and Randomness\n==================================\n\nEverything you use in a smart contract is publicly visible,\neven local variables and state variables marked ``private``.\n\nUsing random numbers in smart contracts is quite tricky if you do not want block builders to be able to cheat.\n\nReentrancy\n==========\n\nAny interaction from a contract (A) with another contract (B)\nand any transfer of Ether hands over control to that contract (B).\nThis makes it possible for B to call back into A before this interaction is completed.\nTo give an example, the following code contains a bug (it is just a snippet and not a complete contract):\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n // THIS CONTRACT CONTAINS A BUG - DO NOT USE\n contract Fund {\n /// @dev Mapping of ether shares of the contract.\n mapping(address => uint) shares;\n /// Withdraw your share.\n function withdraw() public {\n // This will report a warning (deprecation)\n if (payable(msg.sender).send(shares[msg.sender]))\n shares[msg.sender] = 0;\n }\n }\n\nThe problem is not too serious here because of the limited gas as part of ``send``,\nbut it still exposes a weakness:\nEther transfer can always include code execution,\nso the recipient could be a contract that calls back into ``withdraw``.\nThis would let it get multiple refunds and, basically, retrieve all the Ether in the contract.\nIn particular, the following contract will allow an attacker to refund multiple times\nas it uses ``call`` which does not limit the amount of gas that is forwarded by default:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.2 <0.9.0;\n\n // THIS CONTRACT CONTAINS A BUG - DO NOT USE\n contract Fund {\n /// @dev Mapping of ether shares of the contract.\n mapping(address => uint) shares;\n /// Withdraw your share.\n function withdraw() public {\n (bool success,) = msg.sender.call{value: shares[msg.sender]}(\"\");\n if (success)\n shares[msg.sender] = 0;\n }\n }\n\nTo avoid reentrancy, you can use the Checks-Effects-Interactions pattern as demonstrated below:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.2 <0.9.0;\n\n contract Fund {\n /// @dev Mapping of ether shares of the contract.\n mapping(address => uint) shares;\n /// Withdraw your share.\n function withdraw() public {\n uint share = shares[msg.sender];\n shares[msg.sender] = 0;\n (bool success, ) = payable(msg.sender).call{value: share}(\"\");\n require(success);\n }\n }\n\nThe Checks-Effects-Interactions pattern ensures that all code paths through a contract\ncomplete all required checks of the supplied parameters before modifying the contract's state (Checks);\nonly then it makes any changes to the state (Effects);\nit may make calls to functions in other contracts\n*after* all planned state changes have been written to storage (Interactions).\nThis is a common foolproof way to prevent *reentrancy attacks*,\nwhere an externally called malicious contract can double-spend an allowance,\ndouble-withdraw a balance, among other things,\nby using logic that calls back into the original contract before it has finalized its transaction.\n\nNote that reentrancy is not only an effect of Ether transfer\nbut of any function call on another contract.\nFurthermore, you also have to take multi-contract situations into account.\nA called contract could modify the state of another contract you depend on.\n\nGas Limit and Loops\n===================\n\nLoops that do not have a fixed number of iterations, for example,\nloops that depend on storage values, have to be used carefully:\nDue to the block gas limit, transactions can only consume a certain amount of gas.\nEither explicitly or just due to normal operation,\nthe number of iterations in a loop can grow beyond the block gas limit\nwhich can cause the complete contract to be stalled at a certain point.\nThis may not apply to ``view`` functions that are only executed to read data from the blockchain.\nStill, such functions may be called by other contracts as part of on-chain operations and stall those.\nPlease be explicit about such cases in the documentation of your contracts.\n\nSending and Receiving Ether\n===========================\n\n- Neither contracts nor \"externally-owned accounts\" are currently able to prevent someone from sending them Ether.\n Contracts can react on and reject a regular transfer, but there are ways to move Ether without creating a message call.\n One way is to simply \"mine to\" the contract address and the second way is using ``selfdestruct(x)``.\n\n- If a contract receives Ether (without a function being called), either the :ref:`receive Ether `\n or the :ref:`fallback ` function is executed.\n If it does not have a ``receive`` nor a ``fallback`` function, the Ether will be rejected (by throwing an exception).\n During the execution of one of these functions, the contract can only rely on the \"gas stipend\" it is passed (2300 gas)\n being available to it at that time.\n This stipend is not enough to modify storage (do not take this for granted though, the stipend might change with future hard forks).\n To be sure that your contract can receive Ether in that way, check the gas requirements of the receive and fallback functions\n (for example in the \"details\" section in Remix).\n\n- There is a way to forward more gas to the receiving contract using ``addr.call{value: x}(\"\")``.\n This is essentially the same as ``addr.transfer(x)``, only that it forwards all remaining gas,\n subject to additional limits imposed by some EVM versions (such as the `63/64th rule `_\n introduced by ``tangerineWhistle``), and opens up the ability for the recipient to perform more expensive actions\n (and it returns a failure code instead of automatically propagating the error).\n This might include calling back into the sending contract or other state changes you might not have thought of.\n So it allows for great flexibility for honest users but also for malicious actors.\n\n- 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.\n\n- If you want to send Ether using ``address.transfer``, there are certain details to be aware of:\n\n 1. If the recipient is a contract, it causes its receive or fallback function\n to be executed which can, in turn, call back the sending contract.\n 2. Sending Ether can fail due to the call depth going above 1024. Since the\n caller is in total control of the call depth, they can force the\n transfer to fail; take this possibility into account or use ``send`` and\n make sure to always check its return value. Better yet, write your\n contract using a pattern where the recipient can withdraw Ether instead.\n 3. Sending Ether can also fail because the execution of the recipient\n contract requires more than the allotted amount of gas (explicitly by\n using :ref:`require `, :ref:`assert `,\n :ref:`revert ` or because the\n operation is too expensive) - it \"runs out of gas\" (OOG). If you\n use ``transfer`` or ``send`` with a return value check, this might\n provide a means for the recipient to block progress in the sending\n contract. Again, the best practice here is to use a :ref:`\"withdraw\"\n pattern instead of a \"send\" pattern `.\n\nCall Stack Depth\n================\n\nExternal function calls can fail at any time\nbecause they exceed the maximum call stack size limit of 1024.\nIn such situations, Solidity throws an exception.\nMalicious actors might be able to force the call stack to a high value\nbefore they interact with your contract.\nNote that, since `Tangerine Whistle `_ hardfork,\nthe `63/64 rule `_ makes call stack depth attack impractical.\nAlso note that the call stack and the expression stack are unrelated,\neven though both have a size limit of 1024 stack slots.\n\nNote that ``.send()`` does **not** throw an exception if the call stack is depleted\nbut rather returns ``false`` in that case.\nThe low-level functions ``.call()``, ``.delegatecall()`` and ``.staticcall()`` behave in the same way.\n\nAuthorized Proxies\n==================\n\nIf your contract can act as a proxy, i.e. if it can call arbitrary contracts with user-supplied data,\nthen the user can essentially assume the identity of the proxy contract.\nEven if you have other protective measures in place, it is best to build your contract system such\nthat the proxy does not have any permissions (not even for itself).\nIf needed, you can accomplish that using a second proxy:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity ^0.8.0;\n contract ProxyWithMoreFunctionality {\n PermissionlessProxy proxy;\n\n function callOther(address addr, bytes memory payload) public\n returns (bool, bytes memory) {\n return proxy.callOther(addr, payload);\n }\n // Other functions and other functionality\n }\n\n // This is the full contract, it has no other functionality and\n // requires no privileges to work.\n contract PermissionlessProxy {\n function callOther(address addr, bytes memory payload) public\n returns (bool, bytes memory) {\n return addr.call(payload);\n }\n }\n\ntx.origin\n=========\n\nNever use ``tx.origin`` for authorization.\nLet's say you have a wallet contract like this:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n // THIS CONTRACT CONTAINS A BUG - DO NOT USE\n contract TxUserWallet {\n address owner;\n\n constructor() {\n owner = msg.sender;\n }\n\n function transferTo(address payable dest, uint amount) public {\n // THE BUG IS RIGHT HERE, you must use msg.sender instead of tx.origin\n require(tx.origin == owner);\n // This will report a warning (deprecation)\n dest.transfer(amount);\n }\n }\n\nNow someone tricks you into sending Ether to the address of this attack wallet:\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.7.0 <0.9.0;\n interface TxUserWallet {\n function transferTo(address payable dest, uint amount) external;\n }\n\n contract TxAttackWallet {\n address payable owner;\n\n constructor() {\n owner = payable(msg.sender);\n }\n\n receive() external payable {\n TxUserWallet(msg.sender).transferTo(owner, msg.sender.balance);\n }\n }\n\nIf your wallet had checked ``msg.sender`` for authorization, it would get the address of the attack wallet,\ninstead of the owner's address.\nBut by checking ``tx.origin``, it gets the original address that kicked off the transaction,\nwhich is still the owner's address.\nThe attack wallet instantly drains all your funds.\n\n.. _underflow-overflow:\n\nTwo's Complement / Underflows / Overflows\n=========================================\n\nAs in many programming languages, Solidity's integer types are not actually integers.\nThey resemble integers when the values are small, but cannot represent arbitrarily large numbers.\n\nThe following code causes an overflow because the result of the addition is too large\nto be stored in the type ``uint8``:\n\n.. code-block:: solidity\n\n uint8 x = 255;\n uint8 y = 1;\n return x + y;\n\nSolidity has two modes in which it deals with these overflows: Checked and Unchecked or \"wrapping\" mode.\n\nThe default checked mode will detect overflows and cause a failing assertion. You can disable this check\nusing ``unchecked { ... }``, causing the overflow to be silently ignored. The above code would return\n``0`` if wrapped in ``unchecked { ... }``.\n\nEven in checked mode, do not assume you are protected from overflow bugs.\nIn this mode, overflows will always revert. If it is not possible to avoid the\noverflow, this can lead to a smart contract being stuck in a certain state.\n\nIn general, read about the limits of two's complement representation, which even has some\nmore special edge cases for signed numbers.\n\nTry to use ``require`` to limit the size of inputs to a reasonable range and use the\n:ref:`SMT checker` to find potential overflows.\n\n.. _clearing-mappings:\n\nClearing Mappings\n=================\n\nThe Solidity type ``mapping`` (see :ref:`mapping-types`) is a storage-only key-value data structure\nthat does not keep track of the keys that were assigned a non-zero value.\nBecause of that, cleaning a mapping without extra information about the written keys is not possible.\nIf a ``mapping`` is used as the base type of a dynamic storage array,\ndeleting or popping the array will have no effect over the ``mapping`` elements.\nThe same happens, for example, if a ``mapping`` is used as the type of a member field of a ``struct``\nthat is the base type of a dynamic storage array.\nThe ``mapping`` is also ignored in assignments of structs or arrays containing a ``mapping``.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.6.0 <0.9.0;\n\n contract Map {\n mapping(uint => uint)[] array;\n\n function allocate(uint newMaps) public {\n for (uint i = 0; i < newMaps; i++)\n array.push();\n }\n\n function writeMap(uint map, uint key, uint value) public {\n array[map][key] = value;\n }\n\n function readMap(uint map, uint key) public view returns (uint) {\n return array[map][key];\n }\n\n function eraseMaps() public {\n delete array;\n }\n }\n\nConsider the example above and the following sequence of calls: ``allocate(10)``, ``writeMap(4, 128, 256)``.\nAt this point, calling ``readMap(4, 128)`` returns 256.\nIf we call ``eraseMaps``, the length of the state variable ``array`` is zeroed,\nbut since its ``mapping`` elements cannot be zeroed, their information stays alive in the contract's storage.\nAfter deleting ``array``, calling ``allocate(5)`` allows us to access ``array[4]`` again,\nand calling ``readMap(4, 128)`` returns 256 even without another call to ``writeMap``.\n\nIf your ``mapping`` information must be deleted, consider using a library similar to\n`iterable mapping `_,\nallowing you to traverse the keys and delete their values in the appropriate ``mapping``.\n\nInternal Function Pointers in Upgradeable Contracts\n===================================================\n\nUpdating the code of your contract may :ref:`invalidate the values of variables of internal function\ntypes`.\nConsider such values ephemeral and avoid storing them in state variables.\nIf you do, you must ensure that they never persist across code updates and are never used by\nother contracts having access to the same storage space as a result of a delegatecall or account\nabstraction.\n\nMinor Details\n=============\n\n- Types that do not occupy the full 32 bytes might contain \"dirty higher order bits\".\n This is especially important if you access ``msg.data`` - it poses a malleability risk:\n You can craft transactions that call a function ``f(uint8 x)``\n with a raw byte argument of ``0xff000001`` and with ``0x00000001``.\n Both are fed to the contract and both will look like the number ``1`` as far as ``x`` is concerned,\n but ``msg.data`` will be different, so if you use ``keccak256(msg.data)`` for anything,\n you will get different results.\n\n***************\nRecommendations\n***************\n\nTake Warnings Seriously\n=======================\n\nIf the compiler warns you about something, you should change it.\nEven if you do not think that this particular warning has security implications,\nthere might be another issue buried beneath it.\nAny compiler warning we issue can be silenced by slight changes to the code.\n\nAlways use the latest version of the compiler to be notified about all recently introduced warnings.\n\nMessages of type ``info``, issued by the compiler, are not dangerous\nand simply represent extra suggestions and optional information\nthat the compiler thinks might be useful to the user.\n\nRestrict the Amount of Ether\n============================\n\nRestrict the amount of Ether (or other tokens) that can be stored in a smart contract.\nIf your source code, the compiler or the platform has a bug, these funds may be lost.\nIf you want to limit your loss, limit the amount of Ether.\n\nKeep it Small and Modular\n=========================\n\nKeep your contracts small and easily understandable.\nSingle out unrelated functionality in other contracts or into libraries.\nGeneral recommendations about the source code quality of course apply:\nLimit the amount of local variables, the length of functions and so on.\nDocument your functions so that others can see what your intention was\nand whether it is different than what the code does.\n\nUse the Checks-Effects-Interactions Pattern\n===========================================\n\nMost functions will first perform some checks and they should be done first\n(who called the function, are the arguments in range, did they send enough Ether,\ndoes the person have tokens, etc.).\n\nAs the second step, if all checks passed, effects to the state variables of the current contract should be made.\nInteraction with other contracts should be the very last step in any function.\n\nEarly contracts delayed some effects and waited for external function calls to return in a non-error state.\nThis is often a serious mistake because of the reentrancy problem explained above.\n\nNote that, also, calls to known contracts might in turn cause calls to\nunknown contracts, so it is probably better to just always apply this pattern.\n\nInclude a Fail-Safe Mode\n========================\n\nWhile making your system fully decentralized will remove any intermediary,\nit might be a good idea, especially for new code, to include some kind of fail-safe mechanism:\n\nYou can add a function in your smart contract that performs some self-checks like \"Has any Ether leaked?\",\n\"Is the sum of the tokens equal to the balance of the contract?\" or similar things.\nKeep in mind that you cannot use too much gas for that,\nso help through off-chain computations might be needed there.\n\nIf the self-check fails, the contract automatically switches into some kind of \"failsafe\" mode,\nwhich, for example, disables most of the features,\nhands over control to a fixed and trusted third party\nor just converts the contract into a simple \"give me back my Ether\" contract.\n\nAsk for Peer Review\n===================\n\nThe more people examine a piece of code, the more issues are found.\nAsking people to review your code also helps as a cross-check to find out\nwhether your code is easy to understand -\na very important criterion for good smart contracts.\n" }, { "path": "docs/smtchecker.rst", "content": ".. _formal_verification:\n\n##################################\nSMTChecker and Formal Verification\n##################################\n\nUsing formal verification it is possible to perform an automated mathematical\nproof that your source code fulfills a certain formal specification.\nThe specification is still formal (just as the source code), but usually much\nsimpler.\n\nNote that formal verification itself can only help you understand the\ndifference between what you did (the specification) and how you did it\n(the actual implementation). You still need to check whether the specification\nis what you wanted and that you did not miss any unintended effects of it.\n\nSolidity implements a formal verification approach based on\n`SMT (Satisfiability Modulo Theories) `_ and\n`Horn `_ solving.\nThe SMTChecker module automatically tries to prove that the code satisfies the\nspecification given by ``require`` and ``assert`` statements. That is, it considers\n``require`` statements as assumptions and tries to prove that the conditions\ninside ``assert`` statements are always true. If an assertion failure is\nfound, a counterexample may be given to the user showing how the assertion can\nbe violated. If no warning is given by the SMTChecker for a property,\nit means that the property is safe.\n\nThe other verification targets that the SMTChecker checks at compile time are:\n\n- Arithmetic underflow and overflow.\n- Division by zero.\n- Trivial conditions and unreachable code.\n- Popping an empty array.\n- Out of bounds index access.\n- Insufficient funds for a transfer.\n\nAll the targets above are automatically checked by default if all engines are\nenabled, except underflow and overflow for Solidity >=0.8.7.\n\nThe potential warnings that the SMTChecker reports are:\n\n- `` happens here.``. This means that the SMTChecker proved that a certain property fails. A counterexample may be given, however in complex situations it may also not show a counterexample. This result may also be a false positive in certain cases, when the SMT encoding adds abstractions for Solidity code that is either hard or impossible to express.\n- `` might happen here``. This means that the solver could not prove either case within the given timeout. Since the result is unknown, the SMTChecker reports the potential failure for soundness. This may be solved by increasing the query timeout, but the problem might also simply be too hard for the engine to solve.\n\nTo enable the SMTChecker, you must select :ref:`which engine should run`,\nwhere the default is no engine. Selecting the engine enables the SMTChecker on all files.\n\n.. note::\n\n Prior to Solidity 0.8.4, the default way to enable the SMTChecker was via\n ``pragma experimental SMTChecker;`` and only the contracts containing the\n pragma would be analyzed. That pragma has been deprecated, and although it\n still enables the SMTChecker for backwards compatibility, it will be removed\n in Solidity 0.9.0. Note also that now using the pragma even in a single file\n enables the SMTChecker for all files.\n\n.. note::\n\n The lack of warnings for a verification target represents an undisputed\n mathematical proof of correctness, assuming no bugs in the SMTChecker and\n the underlying solver. Keep in mind that these problems are\n *very hard* and sometimes *impossible* to solve automatically in the\n general case. Therefore, several properties might not be solved or might\n lead to false positives for large contracts. Every proven property should\n be seen as an important achievement. For advanced users, see :ref:`SMTChecker Tuning `\n to learn a few options that might help proving more complex\n properties.\n\n********\nTutorial\n********\n\nOverflow\n========\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.0;\n\n contract Overflow {\n uint immutable x;\n uint immutable y;\n\n function add(uint x_, uint y_) internal pure returns (uint) {\n return x_ + y_;\n }\n\n constructor(uint x_, uint y_) {\n (x, y) = (x_, y_);\n }\n\n function stateAdd() public view returns (uint) {\n return add(x, y);\n }\n }\n\nThe contract above shows an overflow check example.\nThe SMTChecker does not check underflow and overflow by default for Solidity >=0.8.7,\nso we need to use the command-line option ``--model-checker-targets \"underflow,overflow\"``\nor the JSON option ``settings.modelChecker.targets = [\"underflow\", \"overflow\"]``.\nSee :ref:`this section for targets configuration`.\nHere, it reports the following:\n\n.. code-block:: text\n\n Warning: CHC: Overflow (resulting value larger than 2**256 - 1) happens here.\n Counterexample:\n x = 1, y = 115792089237316195423570985008687907853269984665640564039457584007913129639935\n = 0\n\n Transaction trace:\n Overflow.constructor(1, 115792089237316195423570985008687907853269984665640564039457584007913129639935)\n State: x = 1, y = 115792089237316195423570985008687907853269984665640564039457584007913129639935\n Overflow.stateAdd()\n Overflow.add(1, 115792089237316195423570985008687907853269984665640564039457584007913129639935) -- internal call\n --> o.sol:9:20:\n |\n 9 | return x_ + y_;\n | ^^^^^^^\n\nIf we add ``require`` statements that filter out overflow cases,\nthe SMTChecker proves that no overflow is reachable (by not reporting warnings):\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.0;\n\n contract Overflow {\n uint immutable x;\n uint immutable y;\n\n function add(uint x_, uint y_) internal pure returns (uint) {\n return x_ + y_;\n }\n\n constructor(uint x_, uint y_) {\n (x, y) = (x_, y_);\n }\n\n function stateAdd() public view returns (uint) {\n require(x < type(uint128).max);\n require(y < type(uint128).max);\n return add(x, y);\n }\n }\n\n\nAssert\n======\n\nAn assertion represents an invariant in your code: a property that must be true\n*for all transactions, including all input and storage values*, otherwise there is a bug.\n\nThe code below defines a function ``f`` that guarantees no overflow.\nFunction ``inv`` defines the specification that ``f`` is monotonically increasing:\nfor every possible pair ``(a, b)``, if ``b > a`` then ``f(b) > f(a)``.\nSince ``f`` is indeed monotonically increasing, the SMTChecker proves that our\nproperty is correct. You are encouraged to play with the property and the function\ndefinition to see what results come out!\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.0;\n\n contract Monotonic {\n function f(uint x) internal pure returns (uint) {\n require(x < type(uint128).max);\n return x * 42;\n }\n\n function inv(uint a, uint b) public pure {\n require(b > a);\n assert(f(b) > f(a));\n }\n }\n\nWe can also add assertions inside loops to verify more complicated properties.\nThe following code searches for the maximum element of an unrestricted array of\nnumbers, and asserts the property that the found element must be greater or\nequal every element in the array.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.0;\n\n contract Max {\n function max(uint[] memory a) public pure returns (uint) {\n uint m = 0;\n for (uint i = 0; i < a.length; ++i)\n if (a[i] > m)\n m = a[i];\n\n for (uint i = 0; i < a.length; ++i)\n assert(m >= a[i]);\n\n return m;\n }\n }\n\nNote that in this example the SMTChecker will automatically try to prove three properties:\n\n1. ``++i`` in the first loop does not overflow.\n2. ``++i`` in the second loop does not overflow.\n3. The assertion is always true.\n\n.. note::\n\n The properties involve loops, which makes it *much much* harder than the previous\n examples, so beware of loops!\n\nAll the properties are correctly proven safe. Feel free to change the\nproperties and/or add restrictions on the array to see different results.\nFor example, changing the code to\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.0;\n\n contract Max {\n function max(uint[] memory a) public pure returns (uint) {\n require(a.length >= 5);\n uint m = 0;\n for (uint i = 0; i < a.length; ++i)\n if (a[i] > m)\n m = a[i];\n\n for (uint i = 0; i < a.length; ++i)\n assert(m > a[i]);\n\n return m;\n }\n }\n\ngives us:\n\n.. code-block:: text\n\n Warning: CHC: Assertion violation happens here.\n Counterexample:\n\n a = [0, 0, 0, 0, 0]\n = 0\n\n Transaction trace:\n Test.constructor()\n Test.max([0, 0, 0, 0, 0])\n --> max.sol:14:4:\n |\n 14 | assert(m > a[i]);\n\n\nState Properties\n================\n\nSo far the examples only demonstrated the use of the SMTChecker over pure code,\nproving properties about specific operations or algorithms.\nA common type of properties in smart contracts are properties that involve the\nstate of the contract. Multiple transactions might be needed to make an assertion\nfail for such a property.\n\nAs an example, consider a 2D grid where both axis have coordinates in the range (-2^127, 2^127 - 1).\nLet us place a robot at position (0, 0). The robot can only move diagonally, one step at a time,\nand cannot move outside the grid. The robot's state machine can be represented by the smart contract\nbelow.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.0;\n\n contract Robot {\n int x = 0;\n int y = 0;\n\n modifier wall {\n require(x > type(int128).min && x < type(int128).max);\n require(y > type(int128).min && y < type(int128).max);\n _;\n }\n\n function moveLeftUp() wall public {\n --x;\n ++y;\n }\n\n function moveLeftDown() wall public {\n --x;\n --y;\n }\n\n function moveRightUp() wall public {\n ++x;\n ++y;\n }\n\n function moveRightDown() wall public {\n ++x;\n --y;\n }\n\n function inv() public view {\n assert((x + y) % 2 == 0);\n }\n }\n\nFunction ``inv`` represents an invariant of the state machine that ``x + y``\nmust be even.\nThe SMTChecker manages to prove that regardless how many commands we give the\nrobot, even if infinitely many, the invariant can *never* fail. The interested\nreader may want to prove that fact manually as well. Hint: this invariant is\ninductive.\n\nWe can also trick the SMTChecker into giving us a path to a certain position we\nthink might be reachable. We can add the property that (2, 4) is *not*\nreachable, by adding the following function.\n\n.. code-block:: solidity\n\n function reach_2_4() public view {\n assert(!(x == 2 && y == 4));\n }\n\nThis property is false, and while proving that the property is false,\nthe SMTChecker tells us exactly *how* to reach (2, 4):\n\n.. code-block:: text\n\n Warning: CHC: Assertion violation happens here.\n Counterexample:\n x = 2, y = 4\n\n Transaction trace:\n Robot.constructor()\n State: x = 0, y = 0\n Robot.moveLeftUp()\n State: x = (- 1), y = 1\n Robot.moveRightUp()\n State: x = 0, y = 2\n Robot.moveRightUp()\n State: x = 1, y = 3\n Robot.moveRightUp()\n State: x = 2, y = 4\n Robot.reach_2_4()\n --> r.sol:35:4:\n |\n 35 | assert(!(x == 2 && y == 4));\n | ^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nNote that the path above is not necessarily deterministic, as there are\nother paths that could reach (2, 4). The choice of which path is shown\nmight change depending on the used solver, its version, or just randomly.\n\nExternal Calls and Reentrancy\n=============================\n\nEvery external call is treated as a call to unknown code by the SMTChecker.\nThe reasoning behind that is that even if the code of the called contract is\navailable at compile time, there is no guarantee that the deployed contract\nwill indeed be the same as the contract where the interface came from at\ncompile time.\n\nIn some cases, it is possible to automatically infer properties over state\nvariables that are still true even if the externally called code can do\nanything, including reenter the caller contract.\n\n.. code-block:: solidity\n\n // SPDX-License-Identifier: GPL-3.0\n pragma solidity >=0.8.0;\n\n interface Unknown {\n function run() external;\n }\n\n contract Mutex {\n uint x;\n bool lock;\n\n Unknown immutable unknown;\n\n constructor(Unknown u) {\n require(address(u) != address(0));\n unknown = u;\n }\n\n modifier mutex {\n require(!lock);\n lock = true;\n _;\n lock = false;\n }\n\n function set(uint x_) mutex public {\n x = x_;\n }\n\n function run() mutex public {\n uint xPre = x;\n unknown.run();\n assert(xPre == x);\n }\n }\n\nThe example above shows a contract that uses a mutex flag to forbid reentrancy.\nThe solver is able to infer that when ``unknown.run()`` is called, the contract\nis already \"locked\", so it would not be possible to change the value of ``x``,\nregardless of what the unknown called code does.\n\nIf we \"forget\" to use the ``mutex`` modifier on function ``set``, the\nSMTChecker is able to synthesize the behavior of the externally called code so\nthat the assertion fails:\n\n.. code-block:: text\n\n Warning: CHC: Assertion violation happens here.\n Counterexample:\n x = 1, lock = true, unknown = 1\n\n Transaction trace:\n Mutex.constructor(1)\n State: x = 0, lock = false, unknown = 1\n Mutex.run()\n unknown.run() -- untrusted external call, synthesized as:\n Mutex.set(1) -- reentrant call\n --> m.sol:32:3:\n |\n 32 | \t\tassert(xPre == x);\n | \t\t^^^^^^^^^^^^^^^^^\n\n\n.. _smtchecker_options:\n\n*****************************\nSMTChecker Options and Tuning\n*****************************\n\nTimeout\n=======\n\nThe SMTChecker uses a hardcoded resource limit (``rlimit``) chosen per solver,\nwhich is not precisely related to time. We chose the ``rlimit`` option as the default\nbecause it gives more determinism guarantees than time inside the solver.\n\nThis options translates roughly to \"a few seconds timeout\" per query. Of course many properties\nare very complex and need a lot of time to be solved, where determinism does not matter.\nIf the SMTChecker does not manage to solve the contract properties with the default ``rlimit``,\na timeout can be given in milliseconds via the CLI option ``--model-checker-timeout