cerc-io/solidity
10
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #14 from ethereum/develop

Browse Source 
Updates
This commit is contained in:
Andy 2023-07-10 21:48:44 -06:00 committed by GitHub
commit 933dbea634
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3484 changed files with 39811 additions and 21000 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.circleci/README.md
View File

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

1
.circleci/cln-asan.supp Normal file
View File

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

59
.circleci/compare_bytecode_reports.sh Executable file
View File

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

1137
.circleci/config.yml
View File

File diff suppressed because it is too large Load Diff

16
.circleci/osx_install_dependencies.sh
View File

@ -52,7 +52,6 @@ function validate_checksum {
if [ ! -f /usr/local/lib/libz3.a ] # if this file does not exists (cache was not restored), rebuild dependencies
then
brew unlink python
brew install boost
brew install cmake
brew install wget
@ -61,11 +60,11 @@ then
./scripts/install_obsolete_jsoncpp_1_7_4.sh
# z3
z3_version="4.11.2"
z3_version="4.12.1"
z3_dir="z3-${z3_version}-x64-osx-10.16"
z3_package="${z3_dir}.zip"
wget "https://github.com/Z3Prover/z3/releases/download/z3-${z3_version}/${z3_package}"
validate_checksum "$z3_package" a56b6c40d9251a963aabe1f15731dd88ad1cb801d0e7b16e45f8b232175e165c
validate_checksum "$z3_package" 7601f844de6d906235140d0f76cca58be7ac716f3e2c29c35845aa24b24f73b9
unzip "$z3_package"
rm "$z3_package"
cp "${z3_dir}/bin/libz3.a" /usr/local/lib
@ -74,18 +73,11 @@ then
rm -r "$z3_dir"
# evmone
evmone_version="0.9.1"
evmone_version="0.10.0"
evmone_package="evmone-${evmone_version}-darwin-x86_64.tar.gz"
wget "https://github.com/ethereum/evmone/releases/download/v${evmone_version}/${evmone_package}"
validate_checksum "$evmone_package" 70420a893a9b1036fcb63526b806d97658db8c373bcab1c3e8382594dc8593e4
validate_checksum "$evmone_package" 1b7773779287d7908baca6b8d556a98800cbd7d6e5c910b55fa507642bc0a15c
tar xzpf "$evmone_package" -C /usr/local
rm "$evmone_package"
# hera
hera_version="0.6.0"
hera_package="hera-${hera_version}-darwin-x86_64.tar.gz"
wget "https://github.com/ewasm/hera/releases/download/v${hera_version}/${hera_package}"
validate_checksum "$hera_package" 82ee57404862705ab314f7a4d04bf2cf29d71e8d209850d66c125527cd287f37
tar xzpf "$hera_package" -C /usr/local
rm "$hera_package"
fi

76
.circleci/parallel_bytecode_report.sh Executable file
View File

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

45
.circleci/parallel_cli_tests.py Executable file
View File

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

11
.circleci/soltest_all.sh
View File

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

2
.clang-format
View File

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

7
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

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

12
.github/ISSUE_TEMPLATE/config.yml vendored
View File

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

5
.github/ISSUE_TEMPLATE/documentation_issue.md vendored
View File

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

6
.github/ISSUE_TEMPLATE/feature_request.md vendored
View File

@ -1,5 +1,11 @@
---
name: Feature Request
about: Ideas, comments or messages asking for a particular functionality to be added
to Solidity.
title: ''
labels: feature
assignees: ''
---
<!--## Prerequisites

7
.github/workflows/buildpack-deps.yml vendored
View File

@ -5,9 +5,10 @@ on:
branches: [ develop ]
paths:
- 'scripts/docker/buildpack-deps/Dockerfile.emscripten'
- 'scripts/docker/buildpack-deps/Dockerfile.ubuntu1604.clang.ossfuzz'
- 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2004.clang'
- 'scripts/docker/buildpack-deps/Dockerfile.ubuntu.clang.ossfuzz'
- 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2004'
- 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2204.clang'
- 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2204'
jobs:
buildpack-deps:
@ -22,7 +23,7 @@ jobs:
strategy:
fail-fast: false
matrix:
image_variant: [emscripten, ubuntu1604.clang.ossfuzz, ubuntu2004.clang, ubuntu2004]
image_variant: [emscripten, ubuntu.clang.ossfuzz, ubuntu2004, ubuntu2204.clang, ubuntu2204]
steps:
- uses: actions/checkout@v2

20
.github/workflows/stale.yml vendored
View File

@ -10,8 +10,8 @@ permissions:
pull-requests: write
env:
BEFORE_ISSUE_STALE: 334
BEFORE_ISSUE_CLOSE: 0 #FIXME: change to 14 days
BEFORE_ISSUE_STALE: 90
BEFORE_ISSUE_CLOSE: 7
BEFORE_PR_STALE: 14
BEFORE_PR_CLOSE: 7
@ -21,21 +21,20 @@ jobs:
steps:
- uses: actions/stale@v6
with:
debug-only: true
debug-only: false
days-before-issue-stale: ${{ env.BEFORE_ISSUE_STALE }}
days-before-issue-close: ${{ env.BEFORE_ISSUE_CLOSE }}
stale-issue-message: |
This issue has been marked as stale due to inactivity for the last ${{ env.BEFORE_ISSUE_STALE }} days.
It will be automatically closed in ${{ env.BEFORE_ISSUE_CLOSE }} days.
close-issue-message: |
Hi everyone! This issue has been closed due to inactivity.
Hi everyone! This issue has been automatically closed due to inactivity.
If you think this issue is still relevant in the latest Solidity version and you have something to [contribute](https://docs.soliditylang.org/en/latest/contributing.html), feel free to reopen.
However, unless the issue is a concrete proposal that can be implemented, we recommend starting a language discussion on the [forum](https://forum.soliditylang.org) instead.
any-of-issue-labels: stale # TODO: remove this when we're done with closing ancient issues
ascending: true # TODO: remove this when we're done with closing ancient issues
ascending: true
stale-issue-label: stale
close-issue-label: closed-due-inactivity
exempt-issue-labels: 'bug :bug:,roadmap,selected-for-development,must have'
close-issue-label: 'closed due inactivity'
exempt-issue-labels: 'bug :bug:,epic,roadmap,selected for development,must have,must have eventually,smt'
stale-pr-message: |
This pull request is stale because it has been open for ${{ env.BEFORE_PR_STALE }} days with no activity.
It will be closed in ${{ env.BEFORE_PR_CLOSE }} days unless the `stale` label is removed.
@ -48,6 +47,5 @@ jobs:
exempt-pr-labels: 'external contribution :star:,roadmap,epic'
exempt-draft-pr: false
exempt-all-milestones: true
# remove-stale-when-updated: true # TODO: uncomment and remove the line below when we're done with closing ancient issues
remove-issue-stale-when-updated: false
operations-per-run: 128
remove-stale-when-updated: true
operations-per-run: 256

61
.github/workflows/triage.yml vendored
View File

@ -1,61 +0,0 @@
name: Add new issues to triage column
on:
issues:
types:
- opened
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ORGANIZATION: ethereum
REPOSITORY: solidity
PROJECT_NUMBER: 43
DRY_RUN: false
jobs:
triage_issues:
runs-on: ubuntu-latest
if: join(github.event.issue.labels) == ''
steps:
- name: Retrieve the content of all columns on the board
run: |
gh api graphql \
--raw-field owner="$ORGANIZATION" \
--field project_number="$PROJECT_NUMBER" \
--raw-field repository_name="$REPOSITORY" \
--raw-field query='
query($owner: String!, $repository_name: String!, $project_number: Int!) {
repository(owner: $owner, name: $repository_name) {
project(number: $project_number) {
columns(first: 10) {
nodes {
id,
name
}
}
}
}
}' > project_columns.json
echo 'COLUMN_ID='$(jq '.data.repository.project.columns.nodes[] | select(.name == "Triage") | .id' project_columns.json) >> $GITHUB_ENV
echo 'COLUMN_NAME='$(jq '.data.repository.project.columns.nodes[] | select(.name == "Triage") | .name' project_columns.json) >> $GITHUB_ENV
- name: Add issue#${{ github.event.issue.number }} to Triage column
env:
ISSUE_ID: ${{ github.event.issue.node_id }}
run: |
echo "Adding issue: ${{ github.event.issue.number }} to column $COLUMN_NAME in project $PROJECT_NUMBER"
if [[ $DRY_RUN == "false" ]]; then
gh api graphql \
--silent \
--raw-field column=$COLUMN_ID \
--raw-field issue=$ISSUE_ID \
--raw-field query='
mutation($column: ID!, $issue: ID!) {
addProjectCard(input: {
projectColumnId: $column,
contentId: $issue
}) {
clientMutationId
}
}'
fi

32
.github/workflows/welcome-external-pr.yml vendored
View File

@ -6,42 +6,16 @@ on:
- opened
env:
ORGANIZATION: Ethereum
DRY_RUN: false
jobs:
comment-external-pr:
runs-on: ubuntu-latest
steps:
- name: Get organization members
id: get_members
env:
GH_TOKEN: ${{ secrets.READ_ORG }}
CONTRIBUTOR: ${{ github.event.pull_request.user.login }}
run: |
gh api graphql \
--raw-field organization="$ORGANIZATION" \
--raw-field query='
query($organization: String!) {
organization(login: $organization) {
team(slug: "Solidity") {
members(first: 100) {
nodes {
login
}
}
}
}
}' > org_members.json
echo "CONTRIBUTOR_IS_ORG_MEMBER=$(
jq \
--arg contributor $CONTRIBUTOR \
'.data.organization.team.members | any(.nodes[].login; . == $contributor)' \
org_members.json
)" >> $GITHUB_OUTPUT
# Note: this step requires that the INTERNAL_CONTRIBUTORS environment variable
# is already defined in the repository with the current json list of internal contributors.
- name: Comment on external contribution PR
if: ${{ steps.get_members.outputs.CONTRIBUTOR_IS_ORG_MEMBER == 'false' }}
if: "!contains(fromJSON(vars.INTERNAL_CONTRIBUTORS), github.event.pull_request.user.login)"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR: ${{ github.event.pull_request.html_url }}

3
.gitignore vendored
View File

@ -27,6 +27,9 @@ __pycache__
*.a
*.lib
# ignore git mergetool backup files
*.orig
# Executables
*.exe
*.out

18
.readthedocs.yml Normal file
View File

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

11
CMakeLists.txt
View File

@ -5,7 +5,7 @@ list(APPEND CMAKE_MODULE_PATH ${ETH_CMAKE_DIR})
# Set the build type, if none was specified.
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
if(EXISTS "${CMAKE_SOURCE_DIR}/.git")
if(EXISTS "${PROJECT_SOURCE_DIR}/.git")
set(DEFAULT_BUILD_TYPE "RelWithDebInfo")
else()
set(DEFAULT_BUILD_TYPE "Release")
@ -21,7 +21,7 @@ include(EthPolicy)
eth_policy()
# project name and version should be set after cmake_policy CMP0048
set(PROJECT_VERSION "0.8.18")
set(PROJECT_VERSION "0.8.21")
# OSX target needed in order to support std::visit
set(CMAKE_OSX_DEPLOYMENT_TARGET "10.14")
project(solidity VERSION ${PROJECT_VERSION} LANGUAGES C CXX)
@ -66,16 +66,16 @@ include(EthUtils)
# Create license.h from LICENSE.txt and template
# Converting to char array is required due to MSVC's string size limit.
file(READ ${CMAKE_SOURCE_DIR}/LICENSE.txt LICENSE_TEXT HEX)
file(READ ${PROJECT_SOURCE_DIR}/LICENSE.txt LICENSE_TEXT HEX)
string(REGEX MATCHALL ".." LICENSE_TEXT "${LICENSE_TEXT}")
string(REGEX REPLACE ";" ",\n\t0x" LICENSE_TEXT "${LICENSE_TEXT}")
set(LICENSE_TEXT "0x${LICENSE_TEXT}")
configure_file("${CMAKE_SOURCE_DIR}/cmake/templates/license.h.in" include/license.h)
configure_file("${PROJECT_SOURCE_DIR}/cmake/templates/license.h.in" include/license.h)
include(EthOptions)
configure_project(TESTS)
set(LATEST_Z3_VERSION "4.11.2")
set(LATEST_Z3_VERSION "4.12.1")
set(MINIMUM_Z3_VERSION "4.8.16")
find_package(Z3)
if (${Z3_FOUND})
@ -140,6 +140,7 @@ add_subdirectory(libevmasm)
add_subdirectory(libyul)
add_subdirectory(libsolidity)
add_subdirectory(libsolc)
add_subdirectory(libstdlib)
add_subdirectory(tools)
if (NOT EMSCRIPTEN)

22
CODING_STYLE.md
View File

@ -51,11 +51,11 @@ To set indentation and tab width settings uniformly, the repository contains an
## 1. Namespaces
1. No `using namespace` declarations in header files.
2. Use `using namespace std;` in cpp files, but avoid importing namespaces from boost and others.
3. All symbols should be declared in a namespace except for final applications.
4. Use anonymous namespaces for helpers whose scope is a cpp file only.
5. Preprocessor symbols should be prefixed with the namespace in all-caps and an underscore.
6. Do not use `std::` qualifier in cpp files (see 2.), except for `std::move`, which will otherwise cause the `check_style` step to fail.
2. `using namespace solidity;` and other project local namespaces is fine in cpp files, and generally encouraged.
3. Avoid `using namespace` at file level for third party libraries, such as boost, ranges, etc.
4. All symbols should be declared in a namespace except for final applications.
5. Use anonymous namespaces for helpers whose scope is a cpp file only.
6. Preprocessor symbols should be prefixed with the namespace in all-caps and an underscore.
Only in the header:
```cpp
@ -66,16 +66,6 @@ std::tuple<float, float> meanAndSigma(std::vector<float> const& _v);
}
```
Only in the cpp file:
```cpp
#include <cassert>
using namespace std;
tuple<float, float> myNamespace::meanAndSigma(vector<float> const& _v)
{
// ...
}
```
## 2. Preprocessor
1. File comment is always at top, and includes:
@ -117,7 +107,7 @@ Use `solAssert` and `solUnimplementedAssert` generously to check assumptions tha
1. {Typename} + {qualifiers} + {name}.
2. Only one per line.
3. Associate */& with type, not variable (at ends with parser, but more readable, and safe if in conjunction with (b)).
4. Favour declarations close to use; don't habitually declare at top of scope ala C.
4. Favour declarations close to use; do not habitually declare at top of scope ala C.
5. Pass non-trivial parameters as const reference, unless the data is to be copied into the function, then either pass by const reference or by value and use std::move.
6. If a function returns multiple values, use std::tuple (std::pair acceptable) or better introduce a struct type. Do not use */& arguments.
7. Use parameters of pointer type only if ``nullptr`` is a valid argument, use references otherwise. Often, ``std::optional`` is better suited than a raw pointer.

134
Changelog.md
View File

@ -1,34 +1,126 @@
### 0.8.18 (unreleased)
### 0.8.21 (unreleased)
Language Features:
* Allow qualified access to events from other contracts.
Compiler Features:
* Commandline Interface: Return exit code ``2`` on uncaught exceptions.
* Commandline Interface: Add `--no-cbor-metadata` that skips CBOR metadata from getting appended at the end of the bytecode.
* EVM: Basic support for the EVM version "Paris".
* Natspec: Add event Natspec inheritance for devdoc.
* Standard JSON: Add a boolean field `settings.metadata.appendCBOR` that skips CBOR metadata from getting appended at the end of the bytecode.
* Yul EVM Code Transform: Generate more optimal code for user-defined functions that always terminate a transaction. No return labels will be pushed for calls to functions that always terminate.
* Yul Optimizer: Allow replacing the previously hard-coded cleanup sequence by specifying custom steps after a colon delimiter (``:``) in the sequence string.
* Yul Optimizer: Eliminate ``keccak256`` calls if the value was already calculated by a previous call and can be reused.
* Language Server: Add basic document hover support.
* Optimizer: Added optimization rule ``and(shl(X, Y), shl(X, Z)) => shl(X, and(Y, Z))``.
* 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.
* SMTChecker: Make ``z3`` the default solver for the BMC and CHC engines instead of all solvers.
* Parser: More detailed error messages about invalid version pragmas.
* Commandline Interface: Add ``--ast-compact-json`` output in assembler mode.
* Commandline Interface: Add ``--ir-ast-json`` and ``--ir-optimized-ast-json`` outputs for Solidity input, providing AST in compact JSON format for IR and optimized IR.
* Commandline Interface: Respect ``--optimize-yul`` and ``--no-optimize-yul`` in compiler mode and accept them in assembler mode as well. ``--optimize --no-optimize-yul`` combination now allows enabling EVM assembly optimizer without enabling Yul optimizer.
* EWasm: Remove EWasm backend.
* Parser: Introduce ``pragma experimental solidity``, which will enable an experimental language mode that in particular has no stability guarantees between non-breaking releases and is not suited for production use.
* SMTChecker: Add ``--model-checker-print-query`` CLI option and ``settings.modelChecker.printQuery`` JSON option to output the SMTChecker queries in the SMTLIB2 format. This requires using `smtlib2` solver only.
* Standard JSON Interface: Add ``ast`` file-level output for Yul input.
* Standard JSON Interface: Add ``irAst`` and ``irOptimizedAst`` contract-level outputs for Solidity input, providing AST in compact JSON format for IR and optimized IR.
* Yul Optimizer: Remove experimental `ReasoningBasedSimplifier` optimization step.
* Yul Optimizer: Stack-to-memory mover is now enabled by default whenever possible for via IR code generation and pure Yul compilation.
Bugfixes:
* Yul Optimizer: Hash hex and decimal literals according to their value instead of their representation, improving the detection of equivalent functions.
* Solidity Upgrade Tool ``solidity-upgrade``: Fix the tool returning success code on uncaught exceptions.
* Commandline Interface: Fix internal error when using ``--stop-after parsing`` and requesting some of the outputs that require full analysis or compilation.
* Commandline Interface: It is no longer possible to specify both ``--optimize-yul`` and ``--no-optimize-yul`` at the same time.
* SMTChecker: Fix encoding of side-effects inside ``if`` and ``ternary conditional``statements in the BMC engine.
* SMTChecker: Fix false negative when a verification target can be violated only by trusted external call from another public function.
* SMTChecker: Fix internal error caused by using external identifier to encode member access to functions that take an internal function as a parameter.
* Standard JSON Interface: Fix an incomplete AST being returned when analysis is interrupted by certain kinds of fatal errors.
* Yul Optimizer: Ensure that the assignment of memory slots for variables moved to memory does not depend on AST IDs that may depend on whether additional files are included during compilation.
* Yul Optimizer: Fix optimized IR being unnecessarily passed through the Yul optimizer again before bytecode generation.
AST Changes:
* AST: Add the ``experimentalSolidity`` field to the ``SourceUnit`` nodes, which indicate whether the experimental parsing mode has been enabled via ``pragma experimental solidity``.
### 0.8.20 (2023-05-10)
Compiler Features:
* Assembler: Use ``push0`` for placing ``0`` on the stack for EVM versions starting from "Shanghai". This decreases the deployment and runtime costs.
* EVM: Set default EVM version to "Shanghai".
* EVM: Support for the EVM Version "Shanghai".
* NatSpec: Add support for NatSpec documentation in ``enum`` definitions.
* NatSpec: Add support for NatSpec documentation in ``struct`` definitions.
* NatSpec: Include NatSpec from events that are emitted by a contract but defined outside of it in userdoc and devdoc output.
* Optimizer: Re-implement simplified version of ``UnusedAssignEliminator`` and ``UnusedStoreEliminator``. It can correctly remove some unused assignments in deeply nested loops that were ignored by the old version.
* Parser: Unary plus is no longer recognized as a unary operator in the AST and triggers an error at the parsing stage (rather than later during the analysis).
* SMTChecker: Add CLI option ``--model-checker-bmc-loop-iterations`` and a JSON option ``settings.modelChecker.bmcLoopIterations`` that specify how many loop iterations the BMC engine should unroll. Note that false negatives are possible when unrolling loops. This is due to the possibility that bmc loop iteration setting is less than actual number of iterations needed to complete a loop.
* SMTChecker: Group all messages about unsupported language features in a single warning. The CLI option ``--model-checker-show-unsupported`` and the JSON option ``settings.modelChecker.showUnsupported`` can be enabled to show the full list.
* SMTChecker: Properties that are proved safe are now reported explicitly at the end of analysis. By default, only the number of safe properties is shown. The CLI option ``--model-checker-show-proved-safe`` and the JSON option ``settings.modelChecker.showProvedSafe`` can be enabled to show the full list of safe properties.
* Standard JSON Interface: Add experimental support for importing ASTs via Standard JSON.
* Yul EVM Code Transform: If available, use ``push0`` instead of ``codesize`` to produce an arbitrary value on stack in order to create equal stack heights between branches.
Bugfixes:
* ABI: Include events in the ABI that are emitted by a contract but defined outside of it.
* Immutables: Disallow initialization of immutables in try/catch statements.
* SMTChecker: Fix false positives in ternary operators that contain verification targets in its branches, directly or indirectly.
AST Changes:
* AST: Add the ``internalFunctionIDs`` field to the AST nodes of contracts containing IDs of functions that may be called via the internal dispatch. The field is a map from function AST IDs to internal dispatch function IDs. These IDs are always generated, but they are only used in via-IR code generation.
* AST: Add the ``usedEvents`` field to ``ContractDefinition`` which contains the AST IDs of all events emitted by the contract as well as all events defined and inherited by the contract.
### 0.8.19 (2023-02-22)
Language Features:
* Allow defining custom operators for user-defined value types via ``using {f as +} for T global`` syntax.
Compiler Features:
* SMTChecker: New trusted mode that assumes that any compile-time available code is the actual used code even in external calls. This can be used via the CLI option ``--model-checker-ext-calls trusted`` or the JSON field ``settings.modelChecker.extCalls: "trusted"``.
Bugfixes:
* Assembler: Avoid duplicating subassembly bytecode where possible.
* Code Generator: Avoid including references to the deployed label of referenced functions if they are called right away.
* ContractLevelChecker: Properly distinguish the case of missing base constructor arguments from having an unimplemented base function.
* SMTChecker: Fix internal error caused by unhandled ``z3`` expressions that come from the solver when bitwise operators are used.
* SMTChecker: Fix internal error when using the custom NatSpec annotation to abstract free functions.
* TypeChecker: Also allow external library functions in ``using for``.
AST Changes:
* AST: Add ``function`` field to ``UnaryOperation`` and ``BinaryOperation`` AST nodes. ``functionList`` in ``UsingForDirective`` AST nodes will now contain ``operator`` and ``definition`` members instead of ``function`` when the list entry defines an operator.
### 0.8.18 (2023-02-01)
Language Features:
* Allow named parameters in mapping types.
Compiler Features:
* Commandline Interface: Add ``--no-cbor-metadata`` that skips CBOR metadata from getting appended at the end of the bytecode.
* Commandline Interface: Return exit code ``2`` on uncaught exceptions.
* EVM: Deprecate ``block.difficulty`` and disallow ``difficulty()`` in inline assembly for EVM versions >= paris. The change is due to the renaming introduced by [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399).
* EVM: Introduce ``block.prevrandao`` in Solidity and ``prevrandao()`` in inline assembly for EVM versions >= paris.
* EVM: Set the default EVM version to "Paris".
* EVM: Support for the EVM version "Paris".
* Language Server: Add basic document hover support.
* Natspec: Add event Natspec inheritance for devdoc.
* Optimizer: Added optimization rule ``and(shl(X, Y), shl(X, Z)) => shl(X, and(Y, Z))``.
* Parser: More detailed error messages about invalid version pragmas.
* SMTChecker: Make ``z3`` the default solver for the BMC and CHC engines instead of all solvers.
* SMTChecker: Support Eldarica as a Horn solver for the CHC engine when using the CLI option ``--model-checker-solvers eld``. The binary ``eld`` must be available in the system.
* Solidity Upgrade Tool: Remove ``solidity-upgrade`` tool.
* Standard JSON: Add a boolean field ``settings.metadata.appendCBOR`` that skips CBOR metadata from getting appended at the end of the bytecode.
* TypeChecker: Warn when using deprecated builtin ``selfdestruct``.
* Yul EVM Code Transform: Generate more optimal code for user-defined functions that always terminate a transaction. No return labels will be pushed for calls to functions that always terminate.
* Yul Optimizer: Allow replacing the previously hard-coded cleanup sequence by specifying custom steps after a colon delimiter (``:``) in the sequence string.
* Yul Optimizer: Eliminate ``keccak256`` calls if the value was already calculated by a previous call and can be reused.
Bugfixes:
* Parser: Disallow several ``indexed`` attributes for the same event parameter.
* Parser: Disallow usage of the ``indexed`` attribute for modifier parameters.
* SMTChecker: Fix display error for negative integers that are one more than powers of two.
* SMTChecker: Improved readability for large integers that are powers of two or almost powers of two in error messages.
* SMTChecker: Fix internal error when a public library function is called internally.
* SMTChecker: Fix internal error on multiple wrong SMTChecker natspec entries.
* SMTChecker: Fix internal error on chain assignments using static fully specified state variables.
* SMTChecker: Fix internal error when using user defined types as mapping indices or struct members.
* SMTChecker: Fix internal error on multiple wrong SMTChecker natspec entries.
* SMTChecker: Fix internal error when a public library function is called internally.
* SMTChecker: Fix internal error when deleting struct member of function type.
* SMTChecker: Fix internal error when using user-defined types as mapping indices or struct members.
* SMTChecker: Improved readability for large integers that are powers of two or almost powers of two in error messages.
* TypeChecker: Fix bug where private library functions could be attached with ``using for`` outside of their declaration scope.
* Yul Optimizer: Hash hex and decimal literals according to their value instead of their representation, improving the detection of equivalent functions.
### 0.8.17 (2022-09-08)

62
ReleaseChecklist.md
View File

@ -7,19 +7,40 @@
- [ ] DockerHub account with push rights to the [``solc`` image](https://hub.docker.com/r/ethereum/solc).
- [ ] Lauchpad (Ubuntu One) account with a membership in the ["Ethereum" team](https://launchpad.net/~ethereum) and
a gnupg key for your email in the ``ethereum.org`` domain (has to be version 1, gpg2 won't work).
- [ ] Ubuntu/Debian dependencies of the PPA scripts: ``devscripts``, ``debhelper``, ``dput``, ``git``, ``wget``, ``ca-certificates``.
- [ ] [npm Registry](https://www.npmjs.com) account added as a collaborator for the [``solc`` package](https://www.npmjs.com/package/solc).
- [ ] Access to the [solidity_lang Twitter account](https://twitter.com/solidity_lang).
- [ ] [Reddit](https://www.reddit.com) account that is at least 10 days old with a minimum of 20 comment karma (``/r/ethereum`` requirements).
### Pre-flight checks
At least a day before the release:
- [ ] Run ``make linkcheck`` from within ``docs/`` and fix any broken links it finds.
Ignore false positives caused by ``href`` anchors and dummy links not meant to work.
- [ ] Double-check that [the most recent docs builds at readthedocs](https://readthedocs.org/projects/solidity/builds/) succeeded.
- [ ] Make sure that all merged PRs that should have changelog entries do have them.
- [ ] Rerun CI on the top commits of main branches in all repositories that do not have daily activity by creating a test branch or PR:
- [ ] ``solc-js``
- [ ] ``solc-bin`` (make sure the bytecode comparison check did run)
- [ ] ``homebrew-ethereum``
- [ ] (Optional) Create a prerelease in our Ubuntu PPA by following the steps in the PPA section below on ``develop`` rather than on a tag.
This is recommended especially when dealing with PPA for the first time, when we add a new Ubuntu version or when the PPA scripts were modified in this release cycle.
- [ ] Verify that the release tarball of ``solc-js`` works.
Bump version locally, add ``soljson.js`` from CI, build it, compare the file structure with the previous version, install it locally and try to use it.
### Drafts
At least a day before the release:
- [ ] Create a draft PR to sort the changelog.
- [ ] Create draft PRs to bump version in ``solidity`` and ``solc-js``.
- [ ] Create a draft of the release on github.
- [ ] Create a draft PR to update soliditylang.org.
- [ ] Create drafts of blog posts.
- [ ] Prepare drafts of Twitter, Reddit and Solidity Forum announcements.
### Blog Post
- [ ] Create a post on [solidity-blog](https://github.com/ethereum/solidity-blog) in the ``Releases`` category and explain some of the new features or concepts.
- [ ] Create a post on [solidity-blog](https://github.com/ethereum/solidity-blog) in the ``Security Alerts`` category in case of important bug(s).
### Documentation check
- [ ] Run ``make linkcheck`` from within ``docs/`` and fix any broken links it finds. Ignore false positives caused by ``href`` anchors and dummy links not meant to work.
### Changelog
- [ ] Make sure that all merged PRs that should have changelog entries do have them.
- [ ] Sort the changelog entries alphabetically and correct any errors you notice. Commit it.
- [ ] Update the changelog to include a release date.
- [ ] Run ``scripts/update_bugs_by_version.py`` to regenerate ``bugs_by_version.json`` from the changelog and ``bugs.json``.
@ -31,8 +52,10 @@
- [ ] Create a [release on GitHub](https://github.com/ethereum/solidity/releases/new).
Set the target to the ``develop`` branch and the tag to the new version, e.g. ``v0.8.5``.
Include the following warning: ``**The release is still in progress and the binaries may not yet be available from all sources.**``.
Don't publish it yet - click the ``Save draft`` button instead.
- [ ] Thank voluntary contributors in the GitHub release notes (use ``git shortlog --summary --email v0.5.3..origin/develop``).
Do not publish it yet - click the ``Save draft`` button instead.
- [ ] Thank voluntary contributors in the GitHub release notes.
Use ``scripts/list_contributors.sh v<previous version>`` to get initial list of names.
Remove different variants of the same name manually before using the output.
- [ ] Check that all tests on the latest commit in ``develop`` are green.
- [ ] Click the ``Publish release`` button on the release page, creating the tag.
- [ ] Wait for the CI runs on the tag itself.
@ -57,13 +80,17 @@
### PPA
- [ ] Create ``.release_ppa_auth`` at the root of your local Solidity checkout and set ``LAUNCHPAD_EMAIL`` and ``LAUNCHPAD_KEYID`` to your key's email and key id.
- [ ] Double-check that the ``DISTRIBUTIONS`` list in ``scripts/release_ppa.sh`` and ``scripts/deps-ppa/static-z3.sh`` contains the most recent versions of Ubuntu.
- [ ] Double-check that the ``DISTRIBUTIONS`` list in ``scripts/release_ppa.sh`` and ``scripts/deps-ppa/static_z3.sh`` contains the most recent versions of Ubuntu.
- [ ] Make sure the [``~ethereum/cpp-build-deps`` PPA repository](https://launchpad.net/~ethereum/+archive/ubuntu/cpp-build-deps) contains ``libz3-static-dev builds`` for all current versions of Ubuntu.
If not, run ``scripts/deps-ppa/static-z3.sh`` and wait for the builds to succeed before continuing.
Note that it may be included in the ``z3-static`` multipackage (follow the ``View package details`` link to check).
If not present, run ``scripts/deps-ppa/static_z3.sh`` and wait for the builds to succeed before continuing.
- [ ] Run ``scripts/release_ppa.sh v$VERSION`` to create the PPA release.
- [ ] Wait for the [``~ethereum/ethereum-static`` PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum-static) build to be finished and published for *all platforms*.
This will create a single package containing static binary for older Ubuntu versions in the [``~ethereum/ethereum-static`` PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum-static)
and separate packages with dynamically-linked binaries for recent versions (those listed in ``DISTRIBUTIONS``) in the [``~ethereum/ethereum`` PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum).
- [ ] Wait for the build to be finished and published for *all architectures* (currently we only build for ``amd64``, but we may add ``arm`` in the future).
**SERIOUSLY: DO NOT PROCEED EARLIER!!!**
*After* the static builds are *published*, copy the static package to the [``~ethereum/ethereum`` PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum)
- [ ] *After* the package with the static build is *published*, use it to create packages for older Ubuntu versions.
Copy the static package to the [``~ethereum/ethereum`` PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum)
for the destination series ``Trusty``, ``Xenial`` and ``Bionic`` while selecting ``Copy existing binaries``.
### Release solc-js
@ -76,12 +103,15 @@
### Post-release
- [ ] Make sure the documentation for the new release has been published successfully.
Go to the [documentation status page at ReadTheDocs](https://readthedocs.org/projects/solidity/) and verify that the new version is listed, works and is marked as default.
- [ ] Remove "still in progress" warning from the release notes.
- [ ] Publish the blog posts.
- [ ] Remove "still in progress" warning from the [release notes](https://github.com/ethereum/solidity/releases).
- [ ] Merge the [blog posts](https://github.com/ethereum/solidity-blog/pulls) related to the release.
- [ ] Create a commit to increase the version number on ``develop`` in ``CMakeLists.txt`` and add a new skeleton changelog entry.
- [ ] Announce on Twitter, including links to the release and the blog post.
Use ``#xp`` at the end of the tweet to automatically cross post the announcement to Fosstodon.
- [ ] Update the release information section [in the source of soliditylang.org](https://github.com/ethereum/solidity-portal/blob/master/index.html).
- [ ] Announce on [Twitter](https://twitter.com/solidity_lang), including links to the release and the blog post.
- [ ] Announce on [Fosstodon](https://fosstodon.org/@solidity/), including links to the release and the blog post.
- [ ] Share the announcement on Reddit in [``/r/ethdev``](https://reddit.com/r/ethdev/), cross-posted to [``/r/ethereum``](https://reddit.com/r/ethereum/).
- [ ] Share the announcement the [Solidity forum](https://forum.soliditylang.org) in the ``Announcements`` category.
- [ ] Update the release information section on [soliditylang.org](https://github.com/ethereum/solidity-portal).
- [ ] Share the announcement on the [Solidity forum](https://forum.soliditylang.org) in the ``Announcements`` category.
- [ ] Share the announcement on [Project Updates](https://discord.com/channels/420394352083337236/798974456704925696)
- [ ] Share the announcement on [`#solidity` channel on Matrix](https://matrix.to/#/#ethereum_solidity:gitter.im)
- [ ] Share the announcement on [`#solc-tooling`](https://matrix.to/#/#solc-tooling:matrix.org)
- [ ] Lean back, wait for bug reports and repeat from step 1 :).

2
ReviewChecklist.md
View File

@ -102,7 +102,7 @@ The following points are all covered by the coding style but come up so often th
already used elsewhere in the same expression.
- [ ] **Indent braces and parentheses in a way that makes nesting clear.**
- [ ] **Use `using namespace` only in `.cpp` files.** Use it for `std` and our own modules.
Avoid unnecessary `std::` prefix in `.cpp` files (except for `std::move`).
Avoid unnecessary `std::` prefix in `.cpp` files (except for `std::move` and `std::forward`).
- [ ] **Use range-based loops and destructuring.**
- [ ] **Include any headers you use directly,** even if they are implicitly included through other headers.

9
cmake/EthCompilerSettings.cmake
View File

@ -28,7 +28,7 @@ if(PEDANTIC)
endif()
# Prevent the path of the source directory from ending up in the binary via __FILE__ macros.
eth_add_cxx_compiler_flag_if_supported("-fmacro-prefix-map=${CMAKE_SOURCE_DIR}=/solidity")
eth_add_cxx_compiler_flag_if_supported("-fmacro-prefix-map=${PROJECT_SOURCE_DIR}=/solidity")
# -Wpessimizing-move warns when a call to std::move would prevent copy elision
# if the argument was not wrapped in a call. This happens when moving a local
@ -65,6 +65,13 @@ if (("${CMAKE_CXX_COMPILER_ID}" MATCHES "GNU") OR ("${CMAKE_CXX_COMPILER_ID}" MA
if(WEXTRA_SEMI)
add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wextra-semi>)
endif()
# See https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;h=6b927b1297e66e26e62e722bf15c921dcbbd25b9
check_cxx_compiler_flag(-Wno-dangling-reference WNO_DANGLING_REFERENCE)
if (WNO_DANGLING_REFERENCE)
add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wno-dangling-reference>)
endif()
eth_add_cxx_compiler_flag_if_supported(-Wfinal-dtor-non-final-class)
eth_add_cxx_compiler_flag_if_supported(-Wnewline-eof)
eth_add_cxx_compiler_flag_if_supported(-Wsuggest-destructor-override)

4
cmake/fmtlib.cmake
View File

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

4
cmake/jsoncpp.cmake
View File

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

4
cmake/range-v3.cmake
View File

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

13
cmake/templates/ewasm_polyfill.in
View File

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

10
docs/050-breaking-changes.rst
View File

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

12
docs/060-breaking-changes.rst
View File

@ -12,7 +12,7 @@ For the full list check
Changes the Compiler Might not Warn About
=========================================
This section lists changes where the behaviour of your code might
This section lists changes where the behavior of your code might
change without the compiler telling you about it.
* The resulting type of an exponentiation is the type of the base. It used to be the smallest type
@ -105,13 +105,13 @@ Interface Changes
=================
This section lists changes that are unrelated to the language itself, but that have an effect on the interfaces of
the compiler. These may change the way how you use the compiler on the command line, how you use its programmable
the compiler. These may change the way how you use the compiler on the command-line, how you use its programmable
interface, or how you analyze the output produced by it.
New Error Reporter
~~~~~~~~~~~~~~~~~~
A new error reporter was introduced, which aims at producing more accessible error messages on the command line.
A new error reporter was introduced, which aims at producing more accessible error messages on the command-line.
It is enabled by default, but passing ``--old-reporter`` falls back to the the deprecated old error reporter.
Metadata Hash Options
@ -119,9 +119,9 @@ Metadata Hash Options
The compiler now appends the `IPFS <https://ipfs.io/>`_ hash of the metadata file to the end of the bytecode by default
(for details, see documentation on :doc:`contract metadata <metadata>`). Before 0.6.0, the compiler appended the
`Swarm <https://ethersphere.github.io/swarm-home/>`_ hash by default, and in order to still support this behaviour,
the new command line option ``--metadata-hash`` was introduced. It allows you to select the hash to be produced and
appended, by passing either ``ipfs`` or ``swarm`` as value to the ``--metadata-hash`` command line option.
`Swarm <https://ethersphere.github.io/swarm-home/>`_ hash by default, and in order to still support this behavior,
the new command-line option ``--metadata-hash`` was introduced. It allows you to select the hash to be produced and
appended, by passing either ``ipfs`` or ``swarm`` as value to the ``--metadata-hash`` command-line option.
Passing the value ``none`` completely removes the hash.
These changes can also be used via the :ref:`Standard JSON Interface<compiler-api>` and effect the metadata JSON generated by the compiler.

12
docs/080-breaking-changes.rst
View File

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

7
docs/Makefile
View File

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

59
docs/_static/css/custom.css vendored
View File

@ -6,9 +6,11 @@ pre {
word-wrap: break-word;
}
.wy-table-responsive table td, .wy-table-responsive table th {
.wy-table-responsive table td,
.wy-table-responsive table th {
white-space: normal;
}
.rst-content table.docutils td {
vertical-align: top;
}
@ -27,8 +29,8 @@ pre {
background: #fafafa;
}
.wy-side-nav-search img.logo {
width: 100px !important;
.wy-side-nav-search > a img.logo {
width: 100px;
padding: 0;
}
@ -38,49 +40,36 @@ pre {
}
/* project version (displayed under project logo) */
.wy-side-nav-search .version {
color: #272525 !important;
.wy-side-nav-search > div.version {
color: #272525;
}
/* menu section headers */
.wy-menu .caption {
color: #65afff !important;
.wy-menu p.caption {
color: #65afff;
}
/* Link to Remix IDE shown next to code snippets */
p.remix-link-container {
position: relative;
right: -100%; /* Positioned next to the the top-right corner of the code block following it. */
}
a.remix-link {
position: absolute; /* Remove it from normal flow not to affect the original position of the snippet. */
top: 0.5em;
width: 3.236em; /* Size of the margin (= right-side padding in .wy-nav-content in the current theme). */
}
a.remix-link .link-icon {
background: url("../img/solid-share-arrow.svg") no-repeat;
.rst-content p.remix-link-container {
display: block;
width: 1.5em;
height: 1.5em;
margin: auto;
text-align: right;
margin: 0;
line-height: 1em;
}
a.remix-link .link-text {
display: none; /* Visible only on hover. */
width: 3.3em; /* Narrow enough to get two lines of text. */
margin: auto;
text-align: center;
font-size: 0.8em;
line-height: normal;
color: black;
.rst-content .remix-link-container a.remix-link {
display: inline-block;
font-size: 0.7em;
padding: 0.1em 0.4em;
background: #e1e4e5;
color: #707070;
}
a.remix-link:hover {
opacity: 0.5;
.rst-content .remix-link-container a.remix-link:hover {
background: #c8cbcc;
}
a.remix-link:hover .link-text {
display: block;
.rst-content div.highlight-solidity,
.rst-content div.highlight-yul {
margin-top: 0;
}

29
docs/_static/css/dark.css vendored
View File

@ -1,7 +1,7 @@
/* links */
.rst-content a:not(:visited) {
color: #aaddff !important;
color: #aaddff;
}
/* code directives */
@ -626,10 +626,27 @@ code.docutils.literal.notranslate {
}
/* Literal.Number.Integer.Long */
/* Link to Remix IDE shown over code snippets */
a.remix-link {
filter: invert(1); /* The icon is black. In dark mode we want it white. */
.rst-content .remix-link-container a.remix-link {
color: black;
}
/* Grammar */
.railroad-diagram {
fill: white;
}
.railroad-diagram path {
stroke: white;
}
.railroad-diagram rect {
stroke: white;
}
.a4 .sig-name {
background-color: transparent !important;
}

6
docs/abi-spec.rst
View File

@ -311,7 +311,7 @@ Use of Dynamic Types
A call to a function with the signature ``f(uint256,uint32[],bytes10,bytes)`` with values
``(0x123, [0x456, 0x789], "1234567890", "Hello, world!")`` is encoded in the following way:
We take the first four bytes of ``sha3("f(uint256,uint32[],bytes10,bytes)")``, i.e. ``0x8be65246``.
We take the first four bytes of ``keccak("f(uint256,uint32[],bytes10,bytes)")``, i.e. ``0x8be65246``.
Then we encode the head parts of all four arguments. For the static types ``uint256`` and ``bytes10``,
these are directly the values we want to pass, whereas for the dynamic types ``uint32[]`` and ``bytes``,
we use the offset in bytes to the start of their data area, measured from the start of the value
@ -563,7 +563,7 @@ A function description is a JSON object with the fields:
blockchain state <pure-functions>`), ``view`` (:ref:`specified to not modify the blockchain
state <view-functions>`), ``nonpayable`` (function does not accept Ether - the default) and ``payable`` (function accepts Ether).
Constructor and fallback function never have ``name`` or ``outputs``. Fallback function doesn't have ``inputs`` either.
Constructor, receive, and fallback never have ``name`` or ``outputs``. Receive and fallback do not have ``inputs`` either.
.. note::
Sending non-zero Ether to non-payable function will revert the transaction.
@ -581,7 +581,7 @@ An event description is a JSON object with fairly similar fields:
* ``name``: the name of the parameter.
* ``type``: the canonical type of the parameter (more below).
* ``components``: used for tuple types (more below).
* ``indexed``: ``true`` if the field is part of the log's topics, ``false`` if it one of the log's data segment.
* ``indexed``: ``true`` if the field is part of the log's topics, ``false`` if it is one of the log's data segments.
- ``anonymous``: ``true`` if the event was declared as ``anonymous``.

2
docs/analysing-compilation-output.rst
View File

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

4
docs/assembly.rst
View File

@ -362,7 +362,7 @@ in memory is automatically considered memory-safe and does not need to be annota
.. warning::
It is your responsibility to make sure that the assembly actually satisfies the memory model. If you annotate
an assembly block as memory-safe, but violate one of the memory assumptions, this **will** lead to incorrect and
undefined behaviour that cannot easily be discovered by testing.
undefined behavior that cannot easily be discovered by testing.
In case you are developing a library that is meant to be compatible across multiple versions
of Solidity, you can use a special comment to annotate an assembly block as memory-safe:
@ -375,4 +375,4 @@ of Solidity, you can use a special comment to annotate an assembly block as memo
}
Note that we will disallow the annotation via comment in a future breaking release; so, if you are not concerned with
backwards-compatibility with older compiler versions, prefer using the dialect string.
backward-compatibility with older compiler versions, prefer using the dialect string.

2
docs/bugs.rst
View File

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

12
docs/bugs_by_version.json
View File

@ -1772,6 +1772,14 @@
"bugs": [],
"released": "2022-09-08"
},
"0.8.18": {
"bugs": [],
"released": "2023-02-01"
},
"0.8.19": {
"bugs": [],
"released": "2023-02-22"
},
"0.8.2": {
"bugs": [
"AbiReencodingHeadOverflowWithStaticArrayCleanup",
@ -1784,6 +1792,10 @@
],
"released": "2021-03-02"
},
"0.8.20": {
"bugs": [],
"released": "2023-05-10"
},
"0.8.3": {
"bugs": [
"AbiReencodingHeadOverflowWithStaticArrayCleanup",

76
docs/cheatsheet.rst
View File

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

6
docs/common-patterns.rst
View File

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

3
docs/conf.py
View File

@ -45,6 +45,7 @@ extensions = [
'sphinx_a4doc',
'html_extra_template_renderer',
'remix_code_links',
'sphinx.ext.imgconverter',
]
a4_base_path = os.path.dirname(__file__) + '/grammar'
@ -63,7 +64,7 @@ master_doc = 'index'
# General information about the project.
project = 'Solidity'
project_copyright = '2016-2021, Ethereum'
project_copyright = '2016-2023, The Solidity Authors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the

3
docs/contracts/constant-state-variables.rst
View File

@ -84,7 +84,8 @@ contract's runtime code before it is returned by replacing all references
to immutables with the values assigned to them. This is important if
you are comparing the
runtime code generated by the compiler with the one actually stored in the
blockchain.
blockchain. The compiler outputs where these immutables are located in the deployed bytecode
in the ``immutableReferences`` field of the :ref:`compiler JSON standard output <compiler-api>`.
.. note::
Immutables that are assigned at their declaration are only considered

2
docs/contracts/creating-contracts.rst
View File

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

2
docs/contracts/events.rst
View File

@ -151,6 +151,6 @@ The output of the above looks like the following (trimmed):
Additional Resources for Understanding Events
=============================================
- `Javascript documentation <https://github.com/ethereum/web3.js/blob/1.x/docs/web3-eth-contract.rst#events>`_
- `JavaScript documentation <https://github.com/web3/web3.js/blob/1.x/docs/web3-eth-contract.rst#events>`_
- `Example usage of events <https://github.com/ethchange/smart-exchange/blob/master/lib/contracts/SmartExchange.sol>`_
- `How to access them in js <https://github.com/ethchange/smart-exchange/blob/master/lib/exchange_transactions.js>`_

5
docs/contracts/function-modifiers.rst
View File

@ -6,7 +6,7 @@
Function Modifiers
******************
Modifiers can be used to change the behaviour of functions in a declarative way.
Modifiers can be used to change the behavior of functions in a declarative way.
For example,
you can use a modifier to automatically check a condition prior to executing the function.
@ -19,6 +19,7 @@ if they are marked ``virtual``. For details, please see
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.1 <0.9.0;
// This will report a warning due to deprecated selfdestruct
contract owned {
constructor() { owner = payable(msg.sender); }
@ -60,7 +61,7 @@ if they are marked ``virtual``. For details, please see
}
contract Register is priced, destructible {
mapping (address => bool) registeredAddresses;
mapping(address => bool) registeredAddresses;
uint price;
constructor(uint initialPrice) { price = initialPrice; }

6
docs/contracts/functions.rst
View File

@ -1,4 +1,4 @@
.. index:: ! functions
.. index:: ! functions, ! function;free
.. _functions:
@ -250,7 +250,7 @@ Reverting a state change is not considered a "state modification", as only chang
state made previously in code that did not have the ``view`` or ``pure`` restriction
are reverted and that code has the option to catch the ``revert`` and not pass it on.
This behaviour is also in line with the ``STATICCALL`` opcode.
This behavior is also in line with the ``STATICCALL`` opcode.
.. warning::
It is not possible to prevent functions from reading the state at the level
@ -277,7 +277,7 @@ This behaviour is also in line with the ``STATICCALL`` opcode.
Special Functions
=================
.. index:: ! receive ether function, function;receive ! receive
.. index:: ! receive ether function, function;receive, ! receive
.. _receive-ether-function:

16
docs/contracts/inheritance.rst
View File

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

108
docs/contracts/using-for.rst
View File

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

4
docs/contracts/visibility-and-getters.rst
View File

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

97
docs/contributing.rst
View File

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

13
docs/control-structures.rst
View File

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

18
docs/examples/blind-auction.rst
View File

@ -16,11 +16,11 @@ Simple Open Auction
===================
The general idea of the following simple auction contract is that everyone can
send their bids during a bidding period. The bids already include sending money
/ Ether in order to bind the bidders to their bid. If the highest bid is
raised, the previous highest bidder gets their money back. After the end of
send their bids during a bidding period. The bids already include sending some compensation,
e.g. Ether, in order to bind the bidders to their bid. If the highest bid is
raised, the previous highest bidder gets their Ether back. After the end of
the bidding period, the contract has to be called manually for the beneficiary
to receive their money - contracts cannot activate themselves.
to receive their Ether - contracts cannot activate themselves.
.. code-block:: solidity
@ -92,19 +92,19 @@ to receive their money - contracts cannot activate themselves.
revert AuctionAlreadyEnded();
// If the bid is not higher, send the
// money back (the revert statement
// Ether back (the revert statement
// will revert all changes in this
// function execution including
// it having received the money).
// it having received the Ether).
if (msg.value <= highestBid)
revert BidNotHighEnough(highestBid);
if (highestBid != 0) {
// Sending back the money by simply using
// Sending back the Ether by simply using
// highestBidder.send(highestBid) is a security risk
// because it could execute an untrusted contract.
// It is always safer to let the recipients
// withdraw their money themselves.
// withdraw their Ether themselves.
pendingReturns[highestBidder] += highestBid;
}
highestBidder = msg.sender;
@ -182,7 +182,7 @@ the contract checks that the hash value is the same as the one provided during
the bidding period.
Another challenge is how to make the auction **binding and blind** at the same
time: The only way to prevent the bidder from just not sending the money after
time: The only way to prevent the bidder from just not sending the Ether after
they won the auction is to make them send it together with the bid. Since value
transfers cannot be blinded in Ethereum, anyone can see the value.

6
docs/examples/micropayment.rst
View File

@ -36,7 +36,7 @@ Creating the signature
Alice does not need to interact with the Ethereum network
to sign the transaction, the process is completely offline.
In this tutorial, we will sign messages in the browser
using `web3.js <https://github.com/ethereum/web3.js>`_ and
using `web3.js <https://github.com/web3/web3.js>`_ and
`MetaMask <https://metamask.io>`_, using the method described in `EIP-712 <https://github.com/ethereum/EIPs/pull/712>`_,
as it provides a number of other security benefits.
@ -86,7 +86,7 @@ Packing arguments
Now that we have identified what information to include in the signed message,
we are ready to put the message together, hash it, and sign it. For simplicity,
we concatenate the data. The `ethereumjs-abi <https://github.com/ethereumjs/ethereumjs-abi>`_
library provides a function called ``soliditySHA3`` that mimics the behaviour of
library provides a function called ``soliditySHA3`` that mimics the behavior of
Solidity's ``keccak256`` function applied to arguments encoded using ``abi.encodePacked``.
Here is a JavaScript function that creates the proper signature for the ``ReceiverPays`` example:
@ -144,6 +144,7 @@ The full contract
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
// This will report a warning due to deprecated selfdestruct
contract ReceiverPays {
address owner = msg.sender;
@ -341,6 +342,7 @@ The full contract
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
// This will report a warning due to deprecated selfdestruct
contract SimplePaymentChannel {
address payable public sender; // The account sending payments.
address payable public recipient; // The account receiving the payments.

4
docs/examples/modular.rst
View File

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

6
docs/examples/safe-remote.rst
View File

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

43
docs/ext/remix_code_links.py
View File

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

25
docs/grammar/SolidityLexer.g4
View File

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

40
docs/grammar/SolidityParser.g4
View File

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

100
docs/index.rst
View File

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

72
docs/installing-solidity.rst
View File

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

4
docs/internals/layout_in_storage.rst
View File

@ -208,7 +208,7 @@ of types), arrays have its ``base`` type, and structs list their ``members`` in
the same format as the top-level ``storage`` (see :ref:`above
<storage-layout-top-level>`).
.. note ::
.. note::
The JSON output format of a contract's storage layout is still considered experimental
and is subject to change in non-breaking releases of Solidity.
@ -232,7 +232,7 @@ value and reference types, types that are encoded packed, and nested types.
uint y;
S s;
address addr;
mapping (uint => mapping (address => bool)) map;
mapping(uint => mapping(address => bool)) map;
uint[] array;
string s1;
bytes b1;

47
docs/internals/optimizer.rst
View File

@ -27,7 +27,7 @@ optimized Yul IR for a Solidity source. Similarly, one can use ``solc --strict-a
for a stand-alone Yul mode.
.. note::
The `peephole optimizer <https://en.wikipedia.org/wiki/Peephole_optimization>`_ and the inliner are always
The `peephole optimizer <https://en.wikipedia.org/wiki/Peephole_optimization>`_ is always
enabled by default and can only be turned off via the :ref:`Standard JSON <compiler-api>`.
You can find more details on both optimizer modules and their optimization steps below.
@ -316,7 +316,6 @@ Abbreviation Full name
``L`` :ref:`load-resolver`
``M`` :ref:`loop-invariant-code-motion`
``r`` :ref:`redundant-assign-eliminator`
``R`` :ref:`reasoning-based-simplifier` - highly experimental
``m`` :ref:`rematerialiser`
``V`` :ref:`SSA-reverser`
``a`` :ref:`SSA-transform`
@ -330,10 +329,6 @@ Abbreviation Full name
Some steps depend on properties ensured by ``BlockFlattener``, ``FunctionGrouper``, ``ForLoopInitRewriter``.
For this reason the Yul optimizer always applies them before applying any steps supplied by the user.
The ReasoningBasedSimplifier is an optimizer step that is currently not enabled
in the default set of steps. It uses an SMT solver to simplify arithmetic expressions
and boolean conditions. It has not received thorough testing or validation yet and can produce
non-reproducible results, so please use with care!
Selecting Optimizations
-----------------------
@ -826,10 +821,10 @@ if the common subexpression eliminator was run right before it.
.. _expression-simplifier:
Expression Simplifier
^^^^^^^^^^^^^^^^^^^^^
ExpressionSimplifier
^^^^^^^^^^^^^^^^^^^^
The Expression Simplifier uses the Dataflow Analyzer and makes use
The ExpressionSimplifier uses the Dataflow Analyzer and makes use
of a list of equivalence transforms on expressions like ``X + 0 -> X``
to simplify the code.
@ -863,22 +858,6 @@ Works best if the code is in SSA form.
Prerequisite: Disambiguator, ForLoopInitRewriter.
.. _reasoning-based-simplifier:
ReasoningBasedSimplifier
^^^^^^^^^^^^^^^^^^^^^^^^
This optimizer uses SMT solvers to check whether ``if`` conditions are constant.
- If ``constraints AND condition`` is UNSAT, the condition is never true and the whole body can be removed.
- If ``constraints AND NOT condition`` is UNSAT, the condition is always true and can be replaced by ``1``.
The simplifications above can only be applied if the condition is movable.
It is only effective on the EVM dialect, but safe to use on other dialects.
Prerequisite: Disambiguator, SSATransform.
Statement-Scale Simplifications
-------------------------------
@ -1162,7 +1141,7 @@ will be transformed into the code below after the Unused Store Eliminator step i
For memory store operations, things are generally simpler, at least in the outermost yul block as all such
statements will be removed if they are never read from in any code path.
At function analysis level, however, the approach is similar to ``sstore``, as we do not know whether the memory location will
be read once we leave the function's scope, so the statement will be removed only if all code code paths lead to a memory overwrite.
be read once we leave the function's scope, so the statement will be removed only if all code paths lead to a memory overwrite.
Best run in SSA form.
@ -1279,8 +1258,8 @@ This is a tiny step that helps in reversing the effects of the SSA transform
if it is combined with the Common Subexpression Eliminator and the
Unused Pruner.
The SSA form we generate is detrimental to code generation on the EVM and
WebAssembly alike because it generates many local variables. It would
The SSA form we generate is detrimental to code generation
because it produces many local variables. It would
be better to just re-use existing variables with assignments instead of
fresh variable declarations.
@ -1398,15 +1377,3 @@ into
}
The LiteralRematerialiser should be run before this step.
WebAssembly specific
--------------------
MainFunction
^^^^^^^^^^^^
Changes the topmost block to be a function with a specific name ("main") which has no
inputs nor outputs.
Depends on the Function Grouper.

2
docs/internals/source_mappings.rst
View File

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

21
docs/introduction-to-smart-contracts.rst
View File

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

14
docs/ir-breaking-changes.rst
View File

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

2
docs/layout-of-source-files.rst
View File

@ -182,7 +182,7 @@ Syntax and Semantics
Solidity supports import statements to help modularise your code that
are similar to those available in JavaScript
(from ES6 on). However, Solidity does not support the concept of
a `default export <https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export#Description>`_.
a `default export <https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export#description>`_.
At a global level, you can use import statements of the following form:

11
docs/make.bat
View File

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

327
docs/metadata.rst
View File

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

4
docs/natspec-format.rst
View File

@ -46,7 +46,7 @@ for the purposes of NatSpec.
- For Vyper, use ``"""`` indented to the inner contents with bare
comments. See the `Vyper
documentation <https://vyper.readthedocs.io/en/latest/natspec.html>`__.
documentation <https://docs.vyperlang.org/en/latest/natspec.html>`__.
The following example shows a contract and a function using all available tags.
@ -58,7 +58,7 @@ The following example shows a contract and a function using all available tags.
This may change in the future.
.. code-block:: Solidity
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.2 < 0.9.0;

15
docs/path-resolution.rst
View File

@ -139,7 +139,7 @@ The initial content of the VFS depends on how you invoke the compiler:
#. **Standard input**
On the command line it is also possible to provide the source by sending it to compiler's
On the command-line it is also possible to provide the source by sending it to compiler's
standard input:
.. code-block:: bash
@ -253,6 +253,7 @@ The compiler resolves the import into a source unit name based on the import pat
#. We start with the source unit name of the importing source unit.
#. The last path segment with preceding slashes is removed from the resolved name.
#. Then, for every segment in the import path, starting from the leftmost one:
- If the segment is ``.``, it is skipped.
- If the segment is ``..``, the last path segment with preceding slashes is removed from the resolved name.
- Otherwise, the segment (preceded by a single slash if the resolved name is not empty), is appended to the resolved name.
@ -344,13 +345,13 @@ of the compiler.
CLI Path Normalization and Stripping
------------------------------------
On the command line the compiler behaves just as you would expect from any other program:
On the command-line the compiler behaves just as you would expect from any other program:
it accepts paths in a format native to the platform and relative paths are relative to the current
working directory.
The source unit names assigned to files whose paths are specified on the command line, however,
The source unit names assigned to files whose paths are specified on the command-line, however,
should not change just because the project is being compiled on a different platform or because the
compiler happens to have been invoked from a different directory.
To achieve this, paths to source files coming from the command line must be converted to a canonical
To achieve this, paths to source files coming from the command-line must be converted to a canonical
form, and, if possible, made relative to the base path or one of the include paths.
The normalization rules are as follows:
@ -407,7 +408,7 @@ The resulting file path becomes the source unit name.
Prior to version 0.8.8, CLI path stripping was not performed and the only normalization applied
was the conversion of path separators.
When working with older versions of the compiler it is recommended to invoke the compiler from
the base path and to only use relative paths on the command line.
the base path and to only use relative paths on the command-line.
.. index:: ! allowed paths, ! --allow-paths, remapping; target
.. _allowed-paths:
@ -420,7 +421,7 @@ locations that are considered safe by default:
- Outside of Standard JSON mode:
- The directories containing input files listed on the command line.
- The directories containing input files listed on the command-line.
- The directories used as :ref:`remapping <import-remapping>` targets.
If the target is not a directory (i.e does not end with ``/``, ``/.`` or ``/..``) the directory
containing the target is used instead.
@ -550,7 +551,7 @@ you checked out to ``/project/dapp-bin_old``, then you can run:
This means that all imports in ``module2`` point to the old version but imports in ``module1``
point to the new version.
Here are the detailed rules governing the behaviour of remappings:
Here are the detailed rules governing the behavior of remappings:
#. **Remappings only affect the translation between import paths and source unit names.**

4
docs/requirements.txt
View File

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

8
docs/resources.rst
View File

@ -23,12 +23,12 @@ Integrated (Ethereum) Development Environments
Python-based development and testing framework for smart contracts targeting the Ethereum Virtual Machine.
* `Dapp <https://dapp.tools/>`_
Tool for building, testing and deploying smart contracts from the command line.
Tool for building, testing and deploying smart contracts from the command-line.
* `Embark <https://framework.embarklabs.io/>`_
Developer platform for building and deploying decentralized applications.
* `Foundry <https://github.com/gakonst/foundry>`_
* `Foundry <https://github.com/foundry-rs/foundry>`_
Fast, portable and modular toolkit for Ethereum application development written in Rust.
* `Hardhat <https://hardhat.org/>`_
@ -37,7 +37,7 @@ Integrated (Ethereum) Development Environments
* `Remix <https://remix.ethereum.org/>`_
Browser-based IDE with integrated compiler and Solidity runtime environment without server-side components.
* `Truffle <https://www.trufflesuite.com/truffle>`_
* `Truffle <https://trufflesuite.com/truffle/>`_
Ethereum development framework.
Editor Integrations
@ -50,7 +50,7 @@ Editor Integrations
* IntelliJ
* `IntelliJ IDEA plugin <https://plugins.jetbrains.com/plugin/9475-intellij-solidity>`_
* `IntelliJ IDEA plugin <https://plugins.jetbrains.com/plugin/9475-solidity/>`_
Solidity plugin for IntelliJ IDEA (and all other JetBrains IDEs).
* Sublime Text

300
docs/security-considerations.rst
View File

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

233
docs/smtchecker.rst
View File

@ -73,7 +73,7 @@ Tutorial
Overflow
========
.. code-block:: Solidity
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
@ -97,7 +97,7 @@ Overflow
The contract above shows an overflow check example.
The SMTChecker does not check underflow and overflow by default for Solidity >=0.8.7,
so we need to use the command line option ``--model-checker-targets "underflow,overflow"``
so we need to use the command-line option ``--model-checker-targets "underflow,overflow"``
or the JSON option ``settings.modelChecker.targets = ["underflow", "overflow"]``.
See :ref:`this section for targets configuration<smtchecker_targets>`.
Here, it reports the following:
@ -122,7 +122,7 @@ Here, it reports the following:
If we add ``require`` statements that filter out overflow cases,
the SMTChecker proves that no overflow is reachable (by not reporting warnings):
.. code-block:: Solidity
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
@ -160,7 +160,7 @@ Since ``f`` is indeed monotonically increasing, the SMTChecker proves that our
property is correct. You are encouraged to play with the property and the function
definition to see what results come out!
.. code-block:: Solidity
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
@ -182,7 +182,7 @@ The following code searches for the maximum element of an unrestricted array of
numbers, and asserts the property that the found element must be greater or
equal every element in the array.
.. code-block:: Solidity
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
@ -216,7 +216,7 @@ All the properties are correctly proven safe. Feel free to change the
properties and/or add restrictions on the array to see different results.
For example, changing the code to
.. code-block:: Solidity
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
@ -268,7 +268,7 @@ Let us place a robot at position (0, 0). The robot can only move diagonally, one
and cannot move outside the grid. The robot's state machine can be represented by the smart contract
below.
.. code-block:: Solidity
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
@ -319,7 +319,7 @@ We can also trick the SMTChecker into giving us a path to a certain position we
think might be reachable. We can add the property that (2, 4) is *not*
reachable, by adding the following function.
.. code-block:: Solidity
.. code-block:: solidity
function reach_2_4() public view {
assert(!(x == 2 && y == 4));
@ -368,7 +368,7 @@ In some cases, it is possible to automatically infer properties over state
variables that are still true even if the externally called code can do
anything, including reenter the caller contract.
.. code-block:: Solidity
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
@ -412,7 +412,7 @@ is already "locked", so it would not be possible to change the value of ``x``,
regardless of what the unknown called code does.
If we "forget" to use the ``mutex`` modifier on function ``set``, the
SMTChecker is able to synthesize the behaviour of the externally called code so
SMTChecker is able to synthesize the behavior of the externally called code so
that the assertion fails:
.. code-block:: text
@ -483,6 +483,14 @@ All targets are checked by default, except underflow and overflow for Solidity >
There is no precise heuristic on how and when to split verification targets,
but it can be useful especially when dealing with large contracts.
Proved Targets
==============
If there are any proved targets, the SMTChecker issues one warning per engine stating
how many targets were proved. If the user wishes to see all the specific
proved targets, the CLI option ``--model-checker-show-proved`` and
the JSON option ``settings.modelChecker.showProved = true`` can be used.
Unproved Targets
================
@ -491,6 +499,23 @@ how many unproved targets there are. If the user wishes to see all the specific
unproved targets, the CLI option ``--model-checker-show-unproved`` and
the JSON option ``settings.modelChecker.showUnproved = true`` can be used.
Unsupported Language Features
=============================
Certain Solidity language features are not completely supported by the SMT
encoding that the SMTChecker applies, for example assembly blocks.
The unsupported construct is abstracted via overapproximation to preserve
soundness, meaning any properties reported safe are safe even though this
feature is unsupported.
However such abstraction may cause false positives when the target properties
depend on the precise behavior of the unsupported feature.
If the encoder encounters such cases it will by default report a generic warning
stating how many unsupported features it has seen.
If the user wishes to see all the specific unsupported features, the CLI option
``--model-checker-show-unsupported`` and the JSON option
``settings.modelChecker.showUnsupported = true`` can be used, where their default
value is ``false``.
Verified Contracts
==================
@ -518,13 +543,195 @@ which has the following form:
"source2.sol": ["contract2", "contract3"]
}
Trusted External Calls
======================
By default, the SMTChecker does not assume that compile-time available code
is the same as the runtime code for external calls. Take the following contracts
as an example:
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
contract Ext {
uint public x;
function setX(uint _x) public { x = _x; }
}
contract MyContract {
function callExt(Ext _e) public {
_e.setX(42);
assert(_e.x() == 42);
}
}
When ``MyContract.callExt`` is called, an address is given as the argument.
At deployment time, we cannot know for sure that address ``_e`` actually
contains a deployment of contract ``Ext``.
Therefore, the SMTChecker will warn that the assertion above can be violated,
which is true, if ``_e`` contains another contract than ``Ext``.
However, it can be useful to treat these external calls as trusted, for example,
to test that different implementations of an interface conform to the same property.
This means assuming that address ``_e`` indeed was deployed as contract ``Ext``.
This mode can be enabled via the CLI option ``--model-checker-ext-calls=trusted``
or the JSON field ``settings.modelChecker.extCalls: "trusted"``.
Please be aware that enabling this mode can make the SMTChecker analysis much more
computationally costly.
An important part of this mode is that it is applied to contract types and high
level external calls to contracts, and not low level calls such as ``call`` and
``delegatecall``. The storage of an address is stored per contract type, and
the SMTChecker assumes that an externally called contract has the type of the
caller expression. Therefore, casting an ``address`` or a contract to
different contract types will yield different storage values and can give
unsound results if the assumptions are inconsistent, such as the example below:
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
contract D {
constructor(uint _x) { x = _x; }
uint public x;
function setX(uint _x) public { x = _x; }
}
contract E {
constructor() { x = 2; }
uint public x;
function setX(uint _x) public { x = _x; }
}
contract C {
function f() public {
address d = address(new D(42));
// `d` was deployed as `D`, so its `x` should be 42 now.
assert(D(d).x() == 42); // should hold
assert(D(d).x() == 43); // should fail
// E and D have the same interface, so the following
// call would also work at runtime.
// However, the change to `E(d)` is not reflected in `D(d)`.
E(d).setX(1024);
// Reading from `D(d)` now will show old values.
// The assertion below should fail at runtime,
// but succeeds in this mode's analysis (unsound).
assert(D(d).x() == 42);
// The assertion below should succeed at runtime,
// but fails in this mode's analysis (false positive).
assert(D(d).x() == 1024);
}
}
Due to the above, make sure that the trusted external calls to a certain
variable of ``address`` or ``contract`` type always have the same caller
expression type.
It is also helpful to cast the called contract's variable as the type of the
most derived type in case of inheritance.
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.0;
interface Token {
function balanceOf(address _a) external view returns (uint);
function transfer(address _to, uint _amt) external;
}
contract TokenCorrect is Token {
mapping (address => uint) balance;
constructor(address _a, uint _b) {
balance[_a] = _b;
}
function balanceOf(address _a) public view override returns (uint) {
return balance[_a];
}
function transfer(address _to, uint _amt) public override {
require(balance[msg.sender] >= _amt);
balance[msg.sender] -= _amt;
balance[_to] += _amt;
}
}
contract Test {
function property_transfer(address _token, address _to, uint _amt) public {
require(_to != address(this));
TokenCorrect t = TokenCorrect(_token);
uint xPre = t.balanceOf(address(this));
require(xPre >= _amt);
uint yPre = t.balanceOf(_to);
t.transfer(_to, _amt);
uint xPost = t.balanceOf(address(this));
uint yPost = t.balanceOf(_to);
assert(xPost == xPre - _amt);
assert(yPost == yPre + _amt);
}
}
Note that in function ``property_transfer``, the external calls are
performed on variable ``t``.
Another caveat of this mode are calls to state variables of contract type
outside the analyzed contract. In the code below, even though ``B`` deploys
``A``, it is also possible for the address stored in ``B.a`` to be called by
anyone outside of ``B`` in between transactions to ``B`` itself. To reflect the
possible changes to ``B.a``, the encoding allows an unbounded number of calls
to be made to ``B.a`` externally. The encoding will keep track of ``B.a``'s
storage, therefore assertion (2) should hold. However, currently the encoding
allows such calls to be made from ``B`` conceptually, therefore assertion (3)
fails. Making the encoding stronger logically is an extension of the trusted
mode and is under development. Note that the encoding does not keep track of
storage for ``address`` variables, therefore if ``B.a`` had type ``address``
the encoding would assume that its storage does not change in between
transactions to ``B``.
.. code-block:: solidity
pragma solidity >=0.8.0;
contract A {
uint public x;
address immutable public owner;
constructor() {
owner = msg.sender;
}
function setX(uint _x) public {
require(msg.sender == owner);
x = _x;
}
}
contract B {
A a;
constructor() {
a = new A();
assert(a.x() == 0); // (1) should hold
}
function g() public view {
assert(a.owner() == address(this)); // (2) should hold
assert(a.x() == 0); // (3) should hold, but fails due to a false positive
}
}
Reported Inferred Inductive Invariants
======================================
For properties that were proved safe with the CHC engine,
the SMTChecker can retrieve inductive invariants that were inferred by the Horn
solver as part of the proof.
Currently two types of invariants can be reported to the user:
Currently only two types of invariants can be reported to the user:
- Contract Invariants: these are properties over the contract's state variables
that are true before and after every possible transaction that the contract may ever run. For example, ``x >= y``, where ``x`` and ``y`` are a contract's state variables.
@ -543,7 +750,7 @@ and modulo operations inside Horn rules. Because of that, by default the
Solidity division and modulo operations are encoded using the constraint
``a = b * d + m`` where ``d = a / b`` and ``m = a % b``.
However, other solvers, such as Eldarica, prefer the syntactically precise operations.
The command line flag ``--model-checker-div-mod-no-slacks`` and the JSON option
The command-line flag ``--model-checker-div-mod-no-slacks`` and the JSON option
``settings.modelChecker.divModNoSlacks`` can be used to toggle the encoding
depending on the used solver preferences.
@ -627,7 +834,7 @@ option ``--model-checker-solvers {all,cvc4,eld,smtlib2,z3}`` or the JSON option
- if ``solc`` is compiled with it;
- if a dynamic ``z3`` library of version >=4.8.x is installed in a Linux system (from Solidity 0.7.6);
- statically in ``soljson.js`` (from Solidity 0.6.9), that is, the Javascript binary of the compiler.
- statically in ``soljson.js`` (from Solidity 0.6.9), that is, the JavaScript binary of the compiler.
.. note::
z3 version 4.8.16 broke ABI compatibility with previous versions and cannot

27
docs/style-guide.rst
View File

@ -16,19 +16,19 @@ Many projects will implement their own style guides. In the event of
conflicts, project specific style guides take precedence.
The structure and many of the recommendations within this style guide were
taken from python's
`pep8 style guide <https://www.python.org/dev/peps/pep-0008/>`_.
taken from Python's
`pep8 style guide <https://peps.python.org/pep-0008/>`_.
The goal of this guide is *not* to be the right way or the best way to write
Solidity code. The goal of this guide is *consistency*. A quote from python's
`pep8 <https://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`_
Solidity code. The goal of this guide is *consistency*. A quote from Python's
`pep8 <https://peps.python.org/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`_
captures this concept well.
.. note::
A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important.
But most importantly: **know when to be inconsistent** -- sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!
But most importantly: **know when to be inconsistent** -- sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And do not hesitate to ask!
***********
@ -448,7 +448,7 @@ No:
y = 2;
longVariable = 3;
Don't include a whitespace in the receive and fallback functions:
Do not include a whitespace in the receive and fallback functions:
Yes:
@ -1284,6 +1284,21 @@ Avoiding Naming Collisions
This convention is suggested when the desired name collides with that of
an existing state variable, function, built-in or otherwise reserved name.
Underscore Prefix for Non-external Functions and Variables
==========================================================
* ``_singleLeadingUnderscore``
This convention is suggested for non-external functions and state variables (``private`` or ``internal``). State variables without a specified visibility are ``internal`` by default.
When designing a smart contract, the public-facing API (functions that can be called by any account)
is an important consideration.
Leading underscores allow you to immediately recognize the intent of such functions,
but more importantly, if you change a function from non-external to external (including ``public``)
and rename it accordingly, this forces you to review every call site while renaming.
This can be an important manual check against unintended external functions
and a common source of security vulnerabilities (avoid find-replace-all tooling for this change).
.. _style_guide_natspec:
*******

7
docs/types/conversion.rst
View File

@ -44,7 +44,7 @@ Explicit Conversions
If the compiler does not allow implicit conversion but you are confident a conversion will work,
an explicit type conversion is sometimes possible. This may
result in unexpected behaviour and allows you to bypass some security
result in unexpected behavior and allows you to bypass some security
features of the compiler, so be sure to test that the
result is what you want and expect!
@ -130,6 +130,7 @@ If the array is shorter than the target type, it will be padded with zeros at th
}
}
.. index:: ! literal;conversion, literal;rational, literal;hexadecimal number
.. _types-conversion-literals:
Conversions between Literals and Elementary Types
@ -152,6 +153,8 @@ that is large enough to represent it without truncation:
converted to an integer type. From 0.8.0, such explicit conversions are as strict as implicit
conversions, i.e., they are only allowed if the literal fits in the resulting range.
.. index:: literal;string, literal;hexadecimal
Fixed-Size Byte Arrays
----------------------
@ -182,6 +185,8 @@ if their number of characters matches the size of the bytes type:
bytes2 e = "x"; // not allowed
bytes2 f = "xyz"; // not allowed
.. index:: literal;address
Addresses
---------

42
docs/types/mapping-types.rst
View File

@ -4,12 +4,13 @@
Mapping Types
=============
Mapping types use the syntax ``mapping(KeyType => ValueType)`` and variables
of mapping type are declared using the syntax ``mapping(KeyType => ValueType) VariableName``.
The ``KeyType`` can be any
built-in value type, ``bytes``, ``string``, or any contract or enum type. Other user-defined
or complex types, such as mappings, structs or array types are not allowed.
``ValueType`` can be any type, including mappings, arrays and structs.
Mapping types use the syntax ``mapping(KeyType KeyName? => ValueType ValueName?)`` and variables of
mapping type are declared using the syntax ``mapping(KeyType KeyName? => ValueType ValueName?)
VariableName``. The ``KeyType`` can be any built-in value type, ``bytes``, ``string``, or any
contract or enum type. Other user-defined or complex types, such as mappings, structs or array types
are not allowed. ``ValueType`` can be any type, including mappings, arrays and structs. ``KeyName``
and ``ValueName`` are optional (so ``mapping(KeyType => ValueType)`` works as well) and can be any
valid identifier that is not a type.
You can think of mappings as `hash tables <https://en.wikipedia.org/wiki/Hash_table>`_, which are virtually initialised
such that every possible key exists and is mapped to a value whose
@ -29,8 +30,10 @@ of contract functions that are publicly visible.
These restrictions are also true for arrays and structs that contain mappings.
You can mark state variables of mapping type as ``public`` and Solidity creates a
:ref:`getter <visibility-and-getters>` for you. The ``KeyType`` becomes a parameter for the getter.
If ``ValueType`` is a value type or a struct, the getter returns ``ValueType``.
:ref:`getter <visibility-and-getters>` for you. The ``KeyType`` becomes a parameter
with name ``KeyName`` (if specified) for the getter.
If ``ValueType`` is a value type or a struct, the getter returns ``ValueType`` with
name ``ValueName`` (if specified).
If ``ValueType`` is an array or a mapping, the getter has one parameter for
each ``KeyType``, recursively.
@ -64,6 +67,25 @@ contract that returns the value at the specified address.
The example below is a simplified version of an
`ERC20 token <https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20.sol>`_.
``_allowances`` is an example of a mapping type inside another mapping type.
In the example below, the optional ``KeyName`` and ``ValueName`` are provided for the mapping.
It does not affect any contract functionality or bytecode, it only sets the ``name`` field
for the inputs and outputs in the ABI for the mapping's getter.
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.18;
contract MappingExampleWithNames {
mapping(address user => uint balance) public balances;
function update(uint newBalance) public {
balances[msg.sender] = newBalance;
}
}
The example below uses ``_allowances`` to record the amount someone else is allowed to withdraw from your account.
.. code-block:: solidity
@ -73,8 +95,8 @@ The example below uses ``_allowances`` to record the amount someone else is allo
contract MappingExample {
mapping (address => uint256) private _balances;
mapping (address => mapping (address => uint256)) private _allowances;
mapping(address => uint256) private _balances;
mapping(address => mapping(address => uint256)) private _allowances;
event Transfer(address indexed from, address indexed to, uint256 value);
event Approval(address indexed owner, address indexed spender, uint256 value);

18
docs/types/reference-types.rst
View File

@ -47,8 +47,8 @@ non-persistent area where function arguments are stored, and behaves mostly like
.. _data-location-assignment:
Data location and assignment behaviour
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Data location and assignment behavior
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Data locations are not only relevant for persistency of data, but also for the semantics of assignments:
@ -235,7 +235,7 @@ with the :ref:`default value<default-value>`.
}
}
.. index:: ! array;literals, ! inline;arrays
.. index:: ! literal;array, ! inline;arrays
Array Literals
^^^^^^^^^^^^^^
@ -582,10 +582,10 @@ and the assignment will effectively garble the length of ``x``.
To be safe, only enlarge bytes arrays by at most one element during a single
assignment and do not simultaneously index-access the array in the same statement.
While the above describes the behaviour of dangling storage references in the
While the above describes the behavior of dangling storage references in the
current version of the compiler, any code with dangling references should be
considered to have *undefined behaviour*. In particular, this means that
any future version of the compiler may change the behaviour of code that
considered to have *undefined behavior*. In particular, this means that
any future version of the compiler may change the behavior of code that
involves dangling references.
Be sure to avoid dangling references in your code!
@ -641,7 +641,7 @@ Array slices are useful to ABI-decode secondary data passed in function paramete
/// after doing basic validation on the address argument.
function forward(bytes calldata payload) external {
bytes4 sig = bytes4(payload[:4]);
// Due to truncating behaviour, bytes4(payload) performs identically.
// Due to truncating behavior, bytes4(payload) performs identically.
// bytes4 sig = bytes4(payload);
if (sig == bytes4(keccak256("setOwner(address)"))) {
address owner = abi.decode(payload[4:], (address));
@ -686,11 +686,11 @@ shown in the following example:
uint fundingGoal;
uint numFunders;
uint amount;
mapping (uint => Funder) funders;
mapping(uint => Funder) funders;
}
uint numCampaigns;
mapping (uint => Campaign) campaigns;
mapping(uint => Campaign) campaigns;
function newCampaign(address payable beneficiary, uint goal) public returns (uint campaignID) {
campaignID = numCampaigns++; // campaignID is return variable

34
docs/types/value-types.rst
View File

@ -4,8 +4,7 @@
Value Types
===========
The following types are also called value types because variables of these
types will always be passed by value, i.e. they are always copied when they
The following are called value types because their variables will always be passed by value, i.e. they are always copied when they
are used as function arguments or in assignments.
.. index:: ! bool, ! true, ! false
@ -47,7 +46,7 @@ access the minimum and maximum value representable by the type.
Integers in Solidity are restricted to a certain range. For example, with ``uint32``, this is ``0`` up to ``2**32 - 1``.
There are two modes in which arithmetic is performed on these types: The "wrapping" or "unchecked" mode and the "checked" mode.
By default, arithmetic is always "checked", which mean that if the result of an operation falls outside the value range
By default, arithmetic is always "checked", meaning that if an operation's result falls outside the value range
of the type, the call is reverted through a :ref:`failing assertion<assert-and-require>`. You can switch to "unchecked" mode
using ``unchecked { ... }``. More details can be found in the section about :ref:`unchecked <unchecked>`.
@ -141,7 +140,7 @@ Exponentiation
Exponentiation is only available for unsigned types in the exponent. The resulting type
of an exponentiation is always equal to the type of the base. Please take care that it is
large enough to hold the result and prepare for potential assertion failures or wrapping behaviour.
large enough to hold the result and prepare for potential assertion failures or wrapping behavior.
.. note::
In checked mode, exponentiation only uses the comparatively cheap ``exp`` opcode for small bases.
@ -182,7 +181,7 @@ Operators:
Address
-------
The address type comes in two flavours, which are largely identical:
The address type comes in two largely identical flavors:
- ``address``: Holds a 20 byte value (size of an Ethereum address).
- ``address payable``: Same as ``address``, but with the additional members ``transfer`` and ``send``.
@ -258,13 +257,13 @@ reverts on failure.
* ``send``
Send is the low-level counterpart of ``transfer``. If the execution fails, the current contract will not stop with an exception, but ``send`` will return ``false``.
``send`` is the low-level counterpart of ``transfer``. If the execution fails, the current contract will not stop with an exception, but ``send`` will return ``false``.
.. warning::
There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1024
(this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order
to make safe Ether transfers, always check the return value of ``send``, use ``transfer`` or even better:
use a pattern where the recipient withdraws the money.
use a pattern where the recipient withdraws the Ether.
* ``call``, ``delegatecall`` and ``staticcall``
@ -424,7 +423,7 @@ Dynamically-sized byte array
``string``:
Dynamically-sized UTF-8-encoded string, see :ref:`arrays`. Not a value-type!
.. index:: address, literal;address
.. index:: address, ! literal;address
.. _address_literals:
@ -440,7 +439,7 @@ an error. You can prepend (for integer types) or append (for bytesNN types) zero
.. note::
The mixed-case address checksum format is defined in `EIP-55 <https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md>`_.
.. index:: literal, literal;rational
.. index:: integer, rational number, ! literal;rational
.. _rational_literals:
@ -518,7 +517,7 @@ regardless of the type of the right (exponent) operand.
uint128 a = 1;
uint128 b = 2.5 + a + 0.5;
.. index:: literal, literal;string, string
.. index:: ! literal;string, string
.. _string_literals:
String Literals and Types
@ -565,6 +564,8 @@ character sequence ``abcdef``.
Any Unicode line terminator which is not a newline (i.e. LF, VF, FF, CR, NEL, LS, PS) is considered to
terminate the string literal. Newline only terminates the string literal if it is not preceded by a ``\``.
.. index:: ! literal;unicode
Unicode Literals
----------------
@ -575,7 +576,7 @@ They also support the very same escape sequences as regular string literals.
string memory a = unicode"Hello 😃";
.. index:: literal, bytes
.. index:: ! literal;hexadecimal, bytes
Hexadecimal Literals
--------------------
@ -589,7 +590,8 @@ of the hexadecimal sequence.
Multiple hexadecimal literals separated by whitespace are concatenated into a single literal:
``hex"00112233" hex"44556677"`` is equivalent to ``hex"0011223344556677"``
Hexadecimal literals behave like :ref:`string literals <string_literals>` and have the same convertibility restrictions.
Hexadecimal literals in some ways behave like :ref:`string literals <string_literals>` but are not
implicitly convertible to the ``string`` type.
.. index:: enum
@ -653,13 +655,13 @@ smallest and respectively largest value of the given enum.
.. _user-defined-value-types:
User Defined Value Types
User-defined Value Types
------------------------
A user defined value type allows creating a zero cost abstraction over an elementary value type.
A user-defined value type allows creating a zero cost abstraction over an elementary value type.
This is similar to an alias, but with stricter type requirements.
A user defined value type is defined using ``type C is V``, where ``C`` is the name of the newly
A user-defined value type is defined using ``type C is V``, where ``C`` is the name of the newly
introduced type and ``V`` has to be a built-in value type (the "underlying type"). The function
``C.wrap`` is used to convert from the underlying type to the custom type. Similarly, the
function ``C.unwrap`` is used to convert from the custom type to the underlying type.
@ -680,7 +682,7 @@ type with 18 decimals and a minimal library to do arithmetic operations on the t
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.8;
// Represent a 18 decimal, 256 bit wide fixed point type using a user defined value type.
// Represent a 18 decimal, 256 bit wide fixed point type using a user-defined value type.
type UFixed256x18 is uint256;
/// A minimal library to do fixed point operations on UFixed256x18.

38
docs/units-and-global-variables.rst
View File

@ -1,8 +1,10 @@
.. index:: ! denomination
**************************************
Units and Globally Available Variables
**************************************
.. index:: wei, finney, szabo, gwei, ether
.. index:: ! wei, ! finney, ! szabo, ! gwei, ! ether, ! denomination;ether
Ether Units
===========
@ -21,7 +23,7 @@ The only effect of the subdenomination suffix is a multiplication by a power of
.. note::
The denominations ``finney`` and ``szabo`` have been removed in version 0.7.0.
.. index:: time, seconds, minutes, hours, days, weeks, years
.. index:: ! seconds, ! minutes, ! hours, ! days, ! weeks, ! years, ! denomination;time
Time Units
==========
@ -52,7 +54,7 @@ interpret a function parameter in days, you can in the following way:
function f(uint start, uint daysAfter) public {
if (block.timestamp >= start + daysAfter * 1 days) {
// ...
// ...
}
}
@ -65,7 +67,7 @@ There are special variables and functions which always exist in the global
namespace and are mainly used to provide information about the blockchain
or are general-use utility functions.
.. index:: abi, block, coinbase, difficulty, encode, number, block;number, timestamp, block;timestamp, msg, data, gas, sender, value, gas price, origin
.. index:: abi, block, coinbase, difficulty, prevrandao, encode, number, block;number, timestamp, block;timestamp, msg, data, gas, sender, value, gas price, origin
Block and Transaction Properties
@ -75,9 +77,10 @@ Block and Transaction Properties
- ``block.basefee`` (``uint``): current block's base fee (`EIP-3198 <https://eips.ethereum.org/EIPS/eip-3198>`_ and `EIP-1559 <https://eips.ethereum.org/EIPS/eip-1559>`_)
- ``block.chainid`` (``uint``): current chain id
- ``block.coinbase`` (``address payable``): current block miner's address
- ``block.difficulty`` (``uint``): current block difficulty
- ``block.difficulty`` (``uint``): current block difficulty (``EVM < Paris``). For other EVM versions it behaves as a deprecated alias for ``block.prevrandao`` (`EIP-4399 <https://eips.ethereum.org/EIPS/eip-4399>`_ )
- ``block.gaslimit`` (``uint``): current block gaslimit
- ``block.number`` (``uint``): current block number
- ``block.prevrandao`` (``uint``): random number provided by the beacon chain (``EVM >= Paris``)
- ``block.timestamp`` (``uint``): current block timestamp as seconds since unix epoch
- ``gasleft() returns (uint256)``: remaining gas
- ``msg.data`` (``bytes calldata``): complete calldata
@ -104,7 +107,7 @@ Block and Transaction Properties
Both the timestamp and the block hash can be influenced by miners to some degree.
Bad actors in the mining community can for example run a casino payout function on a chosen hash
and just retry a different hash if they did not receive any money.
and just retry a different hash if they did not receive any compensation, e.g. Ether.
The current block timestamp must be strictly larger than the timestamp of the last block,
but the only guarantee is that it will be somewhere between the timestamps of two
@ -232,7 +235,7 @@ Mathematical and Cryptographic Functions
the ecrecover function remained unchanged.
This is usually not a problem unless you require signatures to be unique or use them to identify items.
OpenZeppelin have a `ECDSA helper library <https://docs.openzeppelin.com/contracts/4.x/api/utils#ECDSA>`_ that you can use as a wrapper for ``ecrecover`` without this issue.
OpenZeppelin has an `ECDSA helper library <https://docs.openzeppelin.com/contracts/4.x/api/utils#ECDSA>`_ that you can use as a wrapper for ``ecrecover`` without this issue.
.. note::
@ -279,7 +282,7 @@ For more information, see the section on :ref:`address`.
There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1024
(this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order
to make safe Ether transfers, always check the return value of ``send``, use ``transfer`` or even better:
Use a pattern where the recipient withdraws the money.
Use a pattern where the recipient withdraws the Ether.
.. warning::
Due to the fact that the EVM considers a call to a non-existing contract to always succeed,
@ -310,13 +313,16 @@ For more information, see the section on :ref:`address`.
semantics than ``delegatecall``.
.. index:: this, selfdestruct
.. index:: this, selfdestruct, super
Contract Related
Contract-related
----------------
``this`` (current contract's type)
the current contract, explicitly convertible to :ref:`address`
The current contract, explicitly convertible to :ref:`address`
``super``
A contract one level higher in the inheritance hierarchy
``selfdestruct(address payable recipient)``
Destroy the current contract, sending its funds to the given :ref:`address`
@ -326,11 +332,13 @@ Contract Related
- the receiving contract's receive function is not executed.
- the contract is only really destroyed at the end of the transaction and ``revert`` s might "undo" the destruction.
Furthermore, all functions of the current contract are callable directly including the current function.
.. warning::
From version 0.8.18 and up, the use of ``selfdestruct`` in both Solidity and Yul will trigger a
deprecation warning, since the ``SELFDESTRUCT`` opcode will eventually undergo breaking changes in behavior
as stated in `EIP-6049 <https://eips.ethereum.org/EIPS/eip-6049>`_.
.. note::
Prior to version 0.5.0, there was a function called ``suicide`` with the same
semantics as ``selfdestruct``.
@ -394,4 +402,4 @@ These keywords are reserved in Solidity. They might become part of the syntax in
``define``, ``final``, ``implements``, ``in``, ``inline``, ``let``, ``macro``, ``match``,
``mutable``, ``null``, ``of``, ``partial``, ``promise``, ``reference``, ``relocatable``,
``sealed``, ``sizeof``, ``static``, ``supports``, ``switch``, ``typedef``, ``typeof``,
``var``.
``var``.

296
docs/using-the-compiler.rst
View File

@ -15,7 +15,7 @@ Using the Commandline Compiler
Basic Usage
-----------
One of the build targets of the Solidity repository is ``solc``, the solidity commandline compiler.
One of the build targets of the Solidity repository is ``solc``, the Solidity commandline compiler.
Using ``solc --help`` provides you with an explanation of all options. The compiler can produce various outputs, ranging from simple binaries and assembly over an abstract syntax tree (parse tree) to estimations of gas usage.
If you only want to compile a single file, you run it as ``solc --bin sourceFile.sol`` and it will print the binary. If you want to get some of the more advanced output variants of ``solc``, it is probably better to tell it to output everything to separate files using ``solc -o outputDirectory --bin --ast-compact-json --asm sourceFile.sol``.
@ -54,7 +54,7 @@ or ../ <direct-imports>` are treated as relative to the directories specified us
Furthermore, the part of the path added via these options will not appear in the contract metadata.
For security reasons the compiler has :ref:`restrictions on what directories it can access <allowed-paths>`.
Directories of source files specified on the command line and target paths of
Directories of source files specified on the command-line and target paths of
remappings are automatically allowed to be accessed by the file reader, but everything
else is rejected by default.
Additional paths (and their subdirectories) can be allowed via the
@ -114,15 +114,15 @@ Setting the EVM Version to Target
*********************************
When you compile your contract code you can specify the Ethereum virtual machine
version to compile for to avoid particular features or behaviours.
version to compile for to avoid particular features or behaviors.
.. warning::
Compiling for the wrong EVM version can result in wrong, strange and failing
behaviour. Please ensure, especially if running a private chain, that you
behavior. Please ensure, especially if running a private chain, that you
use matching EVM versions.
On the command line, you can select the EVM version as follows:
On the command-line, you can select the EVM version as follows:
.. code-block:: shell
@ -160,7 +160,7 @@ at each version. Backward compatibility is not guaranteed between each version.
- It is possible to access dynamic data returned from function calls.
- ``revert`` opcode introduced, which means that ``revert()`` will not waste gas.
- ``constantinople``
- Opcodes ``create2`, ``extcodehash``, ``shl``, ``shr`` and ``sar`` are available in assembly.
- Opcodes ``create2``, ``extcodehash``, ``shl``, ``shr`` and ``sar`` are available in assembly.
- Shifting operators use shifting opcodes and thus need less gas.
- ``petersburg``
- The compiler behaves the same way as with constantinople.
@ -170,10 +170,12 @@ at each version. Backward compatibility is not guaranteed between each version.
- Gas costs for ``SLOAD``, ``*CALL``, ``BALANCE``, ``EXT*`` and ``SELFDESTRUCT`` increased. The
compiler assumes cold gas costs for such operations. This is relevant for gas estimation and
the optimizer.
- ``london`` (**default**)
- ``london``
- The block's base fee (`EIP-3198 <https://eips.ethereum.org/EIPS/eip-3198>`_ and `EIP-1559 <https://eips.ethereum.org/EIPS/eip-1559>`_) can be accessed via the global ``block.basefee`` or ``basefee()`` in inline assembly.
- ``paris``
- No changes, however the semantics of the ``difficulty`` value have changed (see `EIP-4399 <https://eips.ethereum.org/EIPS/eip-4399>`_).
- Introduces ``prevrandao()`` and ``block.prevrandao``, and changes the semantics of the now deprecated ``block.difficulty``, disallowing ``difficulty()`` in inline assembly (see `EIP-4399 <https://eips.ethereum.org/EIPS/eip-4399>`_).
- ``shanghai`` (**default**)
- Smaller code size and gas savings due to the introduction of ``push0`` (see `EIP-3855 <https://eips.ethereum.org/EIPS/eip-3855>`_).
.. index:: ! standard JSON, ! --standard-json
.. _compiler-api:
@ -201,7 +203,7 @@ Input Description
.. code-block:: javascript
{
// Required: Source code language. Currently supported are "Solidity" and "Yul".
// Required: Source code language. Currently supported are "Solidity", "Yul" and "SolidityAST" (experimental).
"language": "Solidity",
// Required
"sources":
@ -225,9 +227,17 @@ Input Description
"bzzr://56ab...",
"ipfs://Qma...",
"/tmp/path/to/file.sol"
// If files are used, their directories should be added to the command line via
// If files are used, their directories should be added to the command-line via
// `--allow-paths <path>`.
]
// If language is set to "SolidityAST", an AST needs to be supplied under the "ast" key.
// Note that importing ASTs is experimental and in particular that:
// - importing invalid ASTs can produce undefined results and
// - no proper error reporting is available on invalid ASTs.
// Furthermore, note that the AST import only consumes the fields of the AST as
// produced by the compiler in "stopAfter": "parsing" mode and then re-performs
// analysis, so any analysis-based annotations of the AST are ignored upon import.
"ast": { ... } // formatted as the json ast requested with the ``ast`` output selection.
},
"destructible":
{
@ -262,9 +272,9 @@ Input Description
// The peephole optimizer is always on if no details are given,
// use details to switch it off.
"peephole": true,
// The inliner is always on if no details are given,
// use details to switch it off.
"inliner": true,
// The inliner is always off if no details are given,
// use details to switch it on.
"inliner": false,
// The unused jumpdest remover is always on if no details are given,
// use details to switch it off.
"jumpdestRemover": true,
@ -294,7 +304,7 @@ Input Description
// optimization-sequence:clean-up-sequence. For more information see
// "The Optimizer > Selecting Optimizations".
// This field is optional, and if not provided, the default sequences for both
// optimization and clean-up are used. If only one of the options is provivded
// optimization and clean-up are used. If only one of the sequences is provided
// the other will not be run.
// If only the delimiter ":" is provided then neither the optimization nor the clean-up
// sequence will be run.
@ -380,7 +390,9 @@ Input Description
// userdoc - User documentation (natspec)
// metadata - Metadata
// ir - Yul intermediate representation of the code before optimization
// irAst - AST of Yul intermediate representation of the code before optimization
// irOptimized - Intermediate representation after optimization
// irOptimizedAst - AST of intermediate representation after optimization
// storageLayout - Slots, offsets and types of the contract's state variables.
// evm.assembly - New assembly format
// evm.legacyAssembly - Old-style assembly format in JSON
@ -394,10 +406,8 @@ Input Description
// evm.deployedBytecode.immutableReferences - Map from AST ids to bytecode ranges that reference immutables
// evm.methodIdentifiers - The list of function hashes
// evm.gasEstimates - Function gas estimates
// ewasm.wast - Ewasm in WebAssembly S-expressions format
// ewasm.wasm - Ewasm in WebAssembly binary format
//
// Note that using a using `evm`, `evm.bytecode`, `ewasm`, etc. will select every
// Note that using a using `evm`, `evm.bytecode`, etc. will select every
// target part of that output. Additionally, `*` can be used as a wildcard to request everything.
//
"outputSelection": {
@ -433,10 +443,18 @@ Input Description
"divModNoSlacks": false,
// Choose which model checker engine to use: all (default), bmc, chc, none.
"engine": "chc",
// Choose whether external calls should be considered trusted in case the
// code of the called function is available at compile-time.
// For details see the SMTChecker section.
"extCalls": "trusted",
// Choose which types of invariants should be reported to the user: contract, reentrancy.
"invariants": ["contract", "reentrancy"],
// Choose whether to output all proved targets. The default is `false`.
"showProved": true,
// Choose whether to output all unproved targets. The default is `false`.
"showUnproved": true,
// Choose whether to output all unsupported language features. The default is `false`.
"showUnsupported": true,
// Choose which solvers should be used, if available.
// See the Formal Verification section for the solvers description.
"solvers": ["cvc4", "smtlib2", "z3"],
@ -483,7 +501,7 @@ Output Description
// Mandatory: Error type, such as "TypeError", "InternalCompilerError", "Exception", etc.
// See below for complete list of types.
"type": "TypeError",
// Mandatory: Component where the error originated, such as "general", "ewasm", etc.
// Mandatory: Component where the error originated, such as "general" etc.
"component": "general",
// Mandatory ("error", "warning" or "info", but please note that this may be extended in the future)
"severity": "error",
@ -520,8 +538,14 @@ Output Description
"userdoc": {},
// Developer documentation (natspec)
"devdoc": {},
// Intermediate representation (string)
// Intermediate representation before optimization (string)
"ir": "",
// AST of intermediate representation before optimization
"irAst": {/* ... */},
// Intermediate representation after optimization (string)
"irOptimized": "",
// AST of intermediate representation after optimization
"irOptimizedAst": {/* ... */},
// See the Storage Layout documentation.
"storageLayout": {"storage": [/* ... */], "types": {/* ... */} },
// EVM-related outputs
@ -599,13 +623,6 @@ Output Description
"heavyLifting()": "infinite"
}
}
},
// Ewasm related outputs
"ewasm": {
// S-expressions format
"wast": "",
// Binary format (hex string)
"wasm": ""
}
}
}
@ -628,231 +645,6 @@ Error Types
10. ``Exception``: Unknown failure during compilation - this should be reported as an issue.
11. ``CompilerError``: Invalid use of the compiler stack - this should be reported as an issue.
12. ``FatalError``: Fatal error not processed correctly - this should be reported as an issue.
13. ``YulException``: Error during Yul Code generation - this should be reported as an issue.
13. ``YulException``: Error during Yul code generation - this should be reported as an issue.
14. ``Warning``: A warning, which didn't stop the compilation, but should be addressed if possible.
15. ``Info``: Information that the compiler thinks the user might find useful, but is not dangerous and does not necessarily need to be addressed.
.. _compiler-tools:
Compiler Tools
**************
solidity-upgrade
----------------
``solidity-upgrade`` can help you to semi-automatically upgrade your contracts
to breaking language changes. While it does not and cannot implement all
required changes for every breaking release, it still supports the ones, that
would need plenty of repetitive manual adjustments otherwise.
.. note::
``solidity-upgrade`` carries out a large part of the work, but your
contracts will most likely need further manual adjustments. We recommend
using a version control system for your files. This helps reviewing and
eventually rolling back the changes made.
.. warning::
``solidity-upgrade`` is not considered to be complete or free from bugs, so
please use with care.
How it Works
~~~~~~~~~~~~
You can pass (a) Solidity source file(s) to ``solidity-upgrade [files]``. If
these make use of ``import`` statement which refer to files outside the
current source file's directory, you need to specify directories that
are allowed to read and import files from, by passing
``--allow-paths [directory]``. You can ignore missing files by passing
``--ignore-missing``.
``solidity-upgrade`` is based on ``libsolidity`` and can parse, compile and
analyse your source files, and might find applicable source upgrades in them.
Source upgrades are considered to be small textual changes to your source code.
They are applied to an in-memory representation of the source files
given. The corresponding source file is updated by default, but you can pass
``--dry-run`` to simulate to whole upgrade process without writing to any file.
The upgrade process itself has two phases. In the first phase source files are
parsed, and since it is not possible to upgrade source code on that level,
errors are collected and can be logged by passing ``--verbose``. No source
upgrades available at this point.
In the second phase, all sources are compiled and all activated upgrade analysis
modules are run alongside compilation. By default, all available modules are
activated. Please read the documentation on
:ref:`available modules <upgrade-modules>` for further details.
This can result in compilation errors that may
be fixed by source upgrades. If no errors occur, no source upgrades are being
reported and you're done.
If errors occur and some upgrade module reported a source upgrade, the first
reported one gets applied and compilation is triggered again for all given
source files. The previous step is repeated as long as source upgrades are
reported. If errors still occur, you can log them by passing ``--verbose``.
If no errors occur, your contracts are up to date and can be compiled with
the latest version of the compiler.
.. _upgrade-modules:
Available Upgrade Modules
~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------+---------+--------------------------------------------------+
| Module | Version | Description |
+============================+=========+==================================================+
| ``constructor`` | 0.5.0 | Constructors must now be defined using the |
| | | ``constructor`` keyword. |
+----------------------------+---------+--------------------------------------------------+
| ``visibility`` | 0.5.0 | Explicit function visibility is now mandatory, |
| | | defaults to ``public``. |
+----------------------------+---------+--------------------------------------------------+
| ``abstract`` | 0.6.0 | The keyword ``abstract`` has to be used if a |
| | | contract does not implement all its functions. |
+----------------------------+---------+--------------------------------------------------+
| ``virtual`` | 0.6.0 | Functions without implementation outside an |
| | | interface have to be marked ``virtual``. |
+----------------------------+---------+--------------------------------------------------+
| ``override`` | 0.6.0 | When overriding a function or modifier, the new |
| | | keyword ``override`` must be used. |
+----------------------------+---------+--------------------------------------------------+
| ``dotsyntax`` | 0.7.0 | The following syntax is deprecated: |
| | | ``f.gas(...)()``, ``f.value(...)()`` and |
| | | ``(new C).value(...)()``. Replace these calls by |
| | | ``f{gas: ..., value: ...}()`` and |
| | | ``(new C){value: ...}()``. |
+----------------------------+---------+--------------------------------------------------+
| ``now`` | 0.7.0 | The ``now`` keyword is deprecated. Use |
| | | ``block.timestamp`` instead. |
+----------------------------+---------+--------------------------------------------------+
| ``constructor-visibility`` | 0.7.0 | Removes visibility of constructors. |
| | | |
+----------------------------+---------+--------------------------------------------------+
Please read :doc:`0.5.0 release notes <050-breaking-changes>`,
:doc:`0.6.0 release notes <060-breaking-changes>`,
:doc:`0.7.0 release notes <070-breaking-changes>` and :doc:`0.8.0 release notes <080-breaking-changes>` for further details.
Synopsis
~~~~~~~~
.. code-block:: none
Usage: solidity-upgrade [options] contract.sol
Allowed options:
--help Show help message and exit.
--version Show version and exit.
--allow-paths path(s)
Allow a given path for imports. A list of paths can be
supplied by separating them with a comma.
--ignore-missing Ignore missing files.
--modules module(s) Only activate a specific upgrade module. A list of
modules can be supplied by separating them with a comma.
--dry-run Apply changes in-memory only and don't write to input
file.
--verbose Print logs, errors and changes. Shortens output of
upgrade patches.
--unsafe Accept *unsafe* changes.
Bug Reports / Feature Requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you found a bug or if you have a feature request, please
`file an issue <https://github.com/ethereum/solidity/issues/new/choose>`_ on Github.
Example
~~~~~~~
Assume that you have the following contract in ``Source.sol``:
.. code-block:: Solidity
pragma solidity >=0.6.0 <0.6.4;
// This will not compile after 0.7.0
// SPDX-License-Identifier: GPL-3.0
contract C {
// FIXME: remove constructor visibility and make the contract abstract
constructor() internal {}
}
contract D {
uint time;
function f() public payable {
// FIXME: change now to block.timestamp
time = now;
}
}
contract E {
D d;
// FIXME: remove constructor visibility
constructor() public {}
function g() public {
// FIXME: change .value(5) => {value: 5}
d.f.value(5)();
}
}
Required Changes
^^^^^^^^^^^^^^^^
The above contract will not compile starting from 0.7.0. To bring the contract up to date with the
current Solidity version, the following upgrade modules have to be executed:
``constructor-visibility``, ``now`` and ``dotsyntax``. Please read the documentation on
:ref:`available modules <upgrade-modules>` for further details.
Running the Upgrade
^^^^^^^^^^^^^^^^^^^
It is recommended to explicitly specify the upgrade modules by using ``--modules`` argument.
.. code-block:: bash
solidity-upgrade --modules constructor-visibility,now,dotsyntax Source.sol
The command above applies all changes as shown below. Please review them carefully (the pragmas will
have to be updated manually.)
.. code-block:: Solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
abstract contract C {
// FIXME: remove constructor visibility and make the contract abstract
constructor() {}
}
contract D {
uint time;
function f() public payable {
// FIXME: change now to block.timestamp
time = block.timestamp;
}
}
contract E {
D d;
// FIXME: remove constructor visibility
constructor() {}
function g() public {
// FIXME: change .value(5) => {value: 5}
d.f{value: 5}();
}
}

44
docs/yul.rst
View File

@ -85,7 +85,6 @@ It can be compiled using ``solc --strict-assembly``. The builtin functions
It is also possible to implement the same function using a for-loop
instead of with recursion. Here, ``lt(a, b)`` computes whether ``a`` is less than ``b``.
less-than comparison.
.. code-block:: yul
@ -153,7 +152,7 @@ where an object is expected.
Inside a code block, the following elements can be used
(see the later sections for more details):
- literals, i.e. ``0x123``, ``42`` or ``"abc"`` (strings up to 32 characters)
- literals, e.g. ``0x123``, ``42`` or ``"abc"`` (strings up to 32 characters)
- calls to builtin functions, e.g. ``add(1, mload(0))``
- variable declarations, e.g. ``let x := 7``, ``let x := add(y, 3)`` or ``let x`` (initial value of 0 is assigned)
- identifiers (variables), e.g. ``add(3, x)``
@ -167,6 +166,8 @@ Inside a code block, the following elements can be used
Multiple syntactical elements can follow each other simply separated by
whitespace, i.e. there is no terminating ``;`` or newline required.
.. index:: ! literal;in Yul
Literals
--------
@ -239,7 +240,7 @@ they have to be assigned to local variables.
For built-in functions of the EVM, functional expressions
can be directly translated to a stream of opcodes:
You just read the expression from right to left to obtain the
opcodes. In the case of the first line in the example, this
opcodes. In the case of the second line in the example, this
is ``PUSH1 3 PUSH1 0x80 MLOAD ADD PUSH1 0x80 MSTORE``.
For calls to user-defined functions, the arguments are also
@ -751,8 +752,8 @@ This document does not want to be a full description of the Ethereum virtual mac
Please refer to a different document if you are interested in the precise semantics.
Opcodes marked with ``-`` do not return a result and all others return exactly one value.
Opcodes marked with ``F``, ``H``, ``B``, ``C``, ``I`` and ``L`` are present since Frontier, Homestead,
Byzantium, Constantinople, Istanbul or London respectively.
Opcodes marked with ``F``, ``H``, ``B``, ``C``, ``I``, ``L`` and ``P`` are present since Frontier,
Homestead, Byzantium, Constantinople, Istanbul, London or Paris respectively.
In the following, ``mem[a...b)`` signifies the bytes of memory starting at position ``a`` up to
but not including position ``b`` and ``storage[p]`` signifies the storage contents at slot ``p``.
@ -899,18 +900,19 @@ the ``dup`` and ``swap`` instructions as well as ``jump`` instructions, labels a
| revert(p, s) | `-` | B | end execution, revert state changes, return data mem[p...(p+s)) |
+-------------------------+-----+---+-----------------------------------------------------------------+
| selfdestruct(a) | `-` | F | end execution, destroy current contract and send funds to a |
| | | | (deprecated) |
+-------------------------+-----+---+-----------------------------------------------------------------+
| invalid() | `-` | F | end execution with invalid instruction |
+-------------------------+-----+---+-----------------------------------------------------------------+
| log0(p, s) | `-` | F | log without topics and data mem[p...(p+s)) |
| log0(p, s) | `-` | F | log data mem[p...(p+s)) |
+-------------------------+-----+---+-----------------------------------------------------------------+
| log1(p, s, t1) | `-` | F | log with topic t1 and data mem[p...(p+s)) |
| log1(p, s, t1) | `-` | F | log data mem[p...(p+s)) with topic t1 |
+-------------------------+-----+---+-----------------------------------------------------------------+
| log2(p, s, t1, t2) | `-` | F | log with topics t1, t2 and data mem[p...(p+s)) |
| log2(p, s, t1, t2) | `-` | F | log data mem[p...(p+s)) with topics t1, t2 |
+-------------------------+-----+---+-----------------------------------------------------------------+
| log3(p, s, t1, t2, t3) | `-` | F | log with topics t1, t2, t3 and data mem[p...(p+s)) |
| log3(p, s, t1, t2, t3) | `-` | F | log data mem[p...(p+s)) with topics t1, t2, t3 |
+-------------------------+-----+---+-----------------------------------------------------------------+
| log4(p, s, t1, t2, t3, | `-` | F | log with topics t1, t2, t3, t4 and data mem[p...(p+s)) |
| log4(p, s, t1, t2, t3, | `-` | F | log data mem[p...(p+s)) with topics t1, t2, t3, t4 |
| t4) | | | |
+-------------------------+-----+---+-----------------------------------------------------------------+
| chainid() | | I | ID of the executing chain (EIP-1344) |
@ -931,6 +933,8 @@ the ``dup`` and ``swap`` instructions as well as ``jump`` instructions, labels a
+-------------------------+-----+---+-----------------------------------------------------------------+
| difficulty() | | F | difficulty of the current block (see note below) |
+-------------------------+-----+---+-----------------------------------------------------------------+
| prevrandao() | | P | randomness provided by the beacon chain (see note below) |
+-------------------------+-----+---+-----------------------------------------------------------------+
| gaslimit() | | F | block gas limit of the current block |
+-------------------------+-----+---+-----------------------------------------------------------------+
@ -945,13 +949,20 @@ the ``dup`` and ``swap`` instructions as well as ``jump`` instructions, labels a
The remaining bytes will retain their values as of before the call.
.. note::
With the Paris network upgrade the semantics of ``difficulty`` have been changed.
It returns the value of ``prevrandao``, which is a 256-bit value, whereas the highest recorded
The ``difficulty()`` instruction is disallowed in EVM version >= Paris.
With the Paris network upgrade the semantics of the instruction that was previously called
``difficulty`` have been changed and the instruction was renamed to ``prevrandao``.
It can now return arbitrary values in the full 256-bit range, whereas the highest recorded
difficulty value within Ethash was ~54 bits.
This change is described in `EIP-4399 <https://eips.ethereum.org/EIPS/eip-4399>`_.
Please note that irrelevant to which EVM version is selected in the compiler, the semantics of
instructions depend on the final chain of deployment.
.. warning::
From version 0.8.18 and up, the use of ``selfdestruct`` in both Solidity and Yul will trigger a
deprecation warning, since the ``SELFDESTRUCT`` opcode will eventually undergo breaking changes in behavior
as stated in `EIP-6049 <https://eips.ethereum.org/EIPS/eip-6049>`_.
In some internal dialects, there are additional functions:
datasize, dataoffset, datacopy
@ -984,7 +995,7 @@ Its first and only argument must be a string literal and uniquely represents the
Identifiers can be arbitrary but when the compiler produces Yul code from Solidity sources,
it uses a library name qualified with the name of the source unit that defines that library.
To link the code with a particular library address, the same identifier must be provided to the
``--libraries`` option on the command line.
``--libraries`` option on the command-line.
For example this code
@ -1065,12 +1076,12 @@ or even opcodes unknown to the Solidity compiler, care has to be taken
when using ``verbatim`` together with the optimizer. Even when the
optimizer is switched off, the code generator has to determine
the stack layout, which means that e.g. using ``verbatim`` to modify
the stack height can lead to undefined behaviour.
the stack height can lead to undefined behavior.
The following is a non-exhaustive list of restrictions on
verbatim bytecode that are not checked by
the compiler. Violations of these restrictions can result in
undefined behaviour.
undefined behavior.
- Control-flow should not jump into or out of verbatim blocks,
but it can jump within the same verbatim block.
@ -1183,8 +1194,7 @@ An example Yul Object is shown below:
// executing code is the constructor code)
size := datasize("Contract1_deployed")
offset := allocate(size)
// This will turn into a memory->memory copy for Ewasm and
// a codecopy for EVM
// This will turn into a codecopy for EVM
datacopy(offset, dataoffset("Contract1_deployed"), size)
return(offset, size)
}

148
libevmasm/Assembly.cpp
View File

@ -42,7 +42,6 @@
#include <fstream>
#include <limits>
using namespace std;
using namespace solidity;
using namespace solidity::evmasm;
using namespace solidity::langutil;
@ -77,7 +76,7 @@ unsigned Assembly::codeSize(unsigned subTagSize) const
namespace
{
string locationFromSources(StringMap const& _sourceCodes, SourceLocation const& _location)
std::string locationFromSources(StringMap const& _sourceCodes, SourceLocation const& _location)
{
if (!_location.hasText() || _sourceCodes.empty())
return {};
@ -92,7 +91,7 @@ string locationFromSources(StringMap const& _sourceCodes, SourceLocation const&
class Functionalizer
{
public:
Functionalizer (ostream& _out, string const& _prefix, StringMap const& _sourceCodes, Assembly const& _assembly):
Functionalizer (std::ostream& _out, std::string const& _prefix, StringMap const& _sourceCodes, Assembly const& _assembly):
m_out(_out), m_prefix(_prefix), m_sourceCodes(_sourceCodes), m_assembly(_assembly)
{}
@ -105,7 +104,7 @@ public:
printLocation(_debugInfoSelection);
}
string expression = _item.toAssemblyText(m_assembly);
std::string expression = _item.toAssemblyText(m_assembly);
if (!(
_item.canBeFunctional() &&
@ -114,7 +113,7 @@ public:
))
{
flush();
m_out << m_prefix << (_item.type() == Tag ? "" : " ") << expression << endl;
m_out << m_prefix << (_item.type() == Tag ? "" : " ") << expression << std::endl;
return;
}
if (_item.arguments() > 0)
@ -137,8 +136,8 @@ public:
void flush()
{
for (string const& expression: m_pending)
m_out << m_prefix << " " << expression << endl;
for (std::string const& expression: m_pending)
m_out << m_prefix << " " << expression << std::endl;
m_pending.clear();
}
@ -154,7 +153,7 @@ public:
if (m_location.sourceName)
m_out << " " + escapeAndQuoteString(*m_location.sourceName);
if (m_location.hasText())
m_out << ":" << to_string(m_location.start) + ":" + to_string(m_location.end);
m_out << ":" << std::to_string(m_location.start) + ":" + std::to_string(m_location.end);
}
if (_debugInfoSelection.snippet)
@ -165,15 +164,15 @@ public:
m_out << locationFromSources(m_sourceCodes, m_location);
}
m_out << " */" << endl;
m_out << " */" << std::endl;
}
private:
strings m_pending;
SourceLocation m_location;
ostream& m_out;
string const& m_prefix;
std::ostream& m_out;
std::string const& m_prefix;
StringMap const& m_sourceCodes;
Assembly const& m_assembly;
};
@ -181,9 +180,9 @@ private:
}
void Assembly::assemblyStream(
ostream& _out,
std::ostream& _out,
DebugInfoSelection const& _debugInfoSelection,
string const& _prefix,
std::string const& _prefix,
StringMap const& _sourceCodes
) const
{
@ -195,34 +194,34 @@ void Assembly::assemblyStream(
if (!m_data.empty() || !m_subs.empty())
{
_out << _prefix << "stop" << endl;
_out << _prefix << "stop" << std::endl;
for (auto const& i: m_data)
if (u256(i.first) >= m_subs.size())
_out << _prefix << "data_" << toHex(u256(i.first)) << " " << util::toHex(i.second) << endl;
_out << _prefix << "data_" << toHex(u256(i.first)) << " " << util::toHex(i.second) << std::endl;
for (size_t i = 0; i < m_subs.size(); ++i)
{
_out << endl << _prefix << "sub_" << i << ": assembly {\n";
_out << std::endl << _prefix << "sub_" << i << ": assembly {\n";
m_subs[i]->assemblyStream(_out, _debugInfoSelection, _prefix + " ", _sourceCodes);
_out << _prefix << "}" << endl;
_out << _prefix << "}" << std::endl;
}
}
if (m_auxiliaryData.size() > 0)
_out << endl << _prefix << "auxdata: 0x" << util::toHex(m_auxiliaryData) << endl;
_out << std::endl << _prefix << "auxdata: 0x" << util::toHex(m_auxiliaryData) << std::endl;
}
string Assembly::assemblyString(
std::string Assembly::assemblyString(
DebugInfoSelection const& _debugInfoSelection,
StringMap const& _sourceCodes
) const
{
ostringstream tmp;
std::ostringstream tmp;
assemblyStream(tmp, _debugInfoSelection, "", _sourceCodes);
return tmp.str();
}
Json::Value Assembly::assemblyJSON(map<string, unsigned> const& _sourceIndices, bool _includeSourceList) const
Json::Value Assembly::assemblyJSON(std::map<std::string, unsigned> const& _sourceIndices, bool _includeSourceList) const
{
Json::Value root;
root[".code"] = Json::arrayValue;
@ -237,7 +236,7 @@ Json::Value Assembly::assemblyJSON(map<string, unsigned> const& _sourceIndices,
sourceIndex = static_cast<int>(iter->second);
}
auto [name, data] = item.nameAndData();
auto [name, data] = item.nameAndData(m_evmVersion);
Json::Value jsonItem;
jsonItem["name"] = name;
jsonItem["begin"] = item.location().start;
@ -287,7 +286,7 @@ Json::Value Assembly::assemblyJSON(map<string, unsigned> const& _sourceIndices,
for (size_t i = 0; i < m_subs.size(); ++i)
{
std::stringstream hexStr;
hexStr << hex << i;
hexStr << std::hex << i;
data[hexStr.str()] = m_subs[i]->assemblyJSON(_sourceIndices, /*_includeSourceList = */false);
}
}
@ -298,7 +297,7 @@ Json::Value Assembly::assemblyJSON(map<string, unsigned> const& _sourceIndices,
return root;
}
AssemblyItem Assembly::namedTag(string const& _name, size_t _params, size_t _returns, optional<uint64_t> _sourceID)
AssemblyItem Assembly::namedTag(std::string const& _name, size_t _params, size_t _returns, std::optional<uint64_t> _sourceID)
{
assertThrow(!_name.empty(), AssemblyException, "Empty named tag.");
if (m_namedTags.count(_name))
@ -312,21 +311,21 @@ AssemblyItem Assembly::namedTag(string const& _name, size_t _params, size_t _ret
return AssemblyItem{Tag, m_namedTags.at(_name).id};
}
AssemblyItem Assembly::newPushLibraryAddress(string const& _identifier)
AssemblyItem Assembly::newPushLibraryAddress(std::string const& _identifier)
{
h256 h(util::keccak256(_identifier));
m_libraries[h] = _identifier;
return AssemblyItem{PushLibraryAddress, h};
}
AssemblyItem Assembly::newPushImmutable(string const& _identifier)
AssemblyItem Assembly::newPushImmutable(std::string const& _identifier)
{
h256 h(util::keccak256(_identifier));
m_immutables[h] = _identifier;
return AssemblyItem{PushImmutable, h};
}
AssemblyItem Assembly::newImmutableAssignment(string const& _identifier)
AssemblyItem Assembly::newImmutableAssignment(std::string const& _identifier)
{
h256 h(util::keccak256(_identifier));
m_immutables[h] = _identifier;
@ -339,7 +338,7 @@ Assembly& Assembly::optimise(OptimiserSettings const& _settings)
return *this;
}
map<u256, u256> const& Assembly::optimiseInternal(
std::map<u256, u256> const& Assembly::optimiseInternal(
OptimiserSettings const& _settings,
std::set<size_t> _tagsReferencedFromOutside
)
@ -352,7 +351,7 @@ map<u256, u256> const& Assembly::optimiseInternal(
{
OptimiserSettings settings = _settings;
Assembly& sub = *m_subs[subId];
map<u256, u256> const& subTagReplacements = sub.optimiseInternal(
std::map<u256, u256> const& subTagReplacements = sub.optimiseInternal(
settings,
JumpdestRemover::referencedTags(m_items, subId)
);
@ -360,7 +359,7 @@ map<u256, u256> const& Assembly::optimiseInternal(
BlockDeduplicator::applyTagReplacement(m_items, subTagReplacements, subId);
}
map<u256, u256> tagReplacements;
std::map<u256, u256> tagReplacements;
// Iterate until no new optimisation possibilities are found.
for (unsigned count = 1; count > 0;)
{
@ -401,7 +400,7 @@ map<u256, u256> const& Assembly::optimiseInternal(
for (auto const& replacement: deduplicator.replacedTags())
{
assertThrow(
replacement.first <= numeric_limits<size_t>::max() && replacement.second <= numeric_limits<size_t>::max(),
replacement.first <= std::numeric_limits<size_t>::max() && replacement.second <= std::numeric_limits<size_t>::max(),
OptimizerException,
"Invalid tag replacement."
);
@ -494,7 +493,7 @@ LinkerObject const& Assembly::assemble() const
LinkerObject& ret = m_assembledObject;
size_t subTagSize = 1;
map<u256, pair<string, vector<size_t>>> immutableReferencesBySub;
std::map<u256, std::pair<std::string, std::vector<size_t>>> immutableReferencesBySub;
for (auto const& sub: m_subs)
{
auto const& linkerObject = sub->assemble();
@ -508,7 +507,7 @@ LinkerObject const& Assembly::assemble() const
immutableReferencesBySub = linkerObject.immutableReferences;
}
for (size_t tagPos: sub->m_tagPositionsInBytecode)
if (tagPos != numeric_limits<size_t>::max() && tagPos > subTagSize)
if (tagPos != std::numeric_limits<size_t>::max() && tagPos > subTagSize)
subTagSize = tagPos;
}
@ -531,11 +530,11 @@ LinkerObject const& Assembly::assemble() const
);
unsigned bytesRequiredForCode = codeSize(static_cast<unsigned>(subTagSize));
m_tagPositionsInBytecode = vector<size_t>(m_usedTags, numeric_limits<size_t>::max());
map<size_t, pair<size_t, size_t>> tagRef;
multimap<h256, unsigned> dataRef;
multimap<size_t, size_t> subRef;
vector<unsigned> sizeRef; ///< Pointers to code locations where the size of the program is inserted
m_tagPositionsInBytecode = std::vector<size_t>(m_usedTags, std::numeric_limits<size_t>::max());
std::map<size_t, std::pair<size_t, size_t>> tagRef;
std::multimap<h256, unsigned> dataRef;
std::multimap<size_t, size_t> subRef;
std::vector<unsigned> sizeRef; ///< Pointers to code locations where the size of the program is inserted
unsigned bytesPerTag = numberEncodingSize(bytesRequiredForCode);
uint8_t tagPush = static_cast<uint8_t>(pushInstruction(bytesPerTag));
@ -550,7 +549,7 @@ LinkerObject const& Assembly::assemble() const
for (AssemblyItem const& i: m_items)
{
// store position of the invalid jump destination
if (i.type() != Tag && m_tagPositionsInBytecode[0] == numeric_limits<size_t>::max())
if (i.type() != Tag && m_tagPositionsInBytecode[0] == std::numeric_limits<size_t>::max())
m_tagPositionsInBytecode[0] = ret.bytecode.size();
switch (i.type())
@ -560,11 +559,18 @@ LinkerObject const& Assembly::assemble() const
break;
case Push:
{
unsigned b = max<unsigned>(1, numberEncodingSize(i.data()));
unsigned b = numberEncodingSize(i.data());
if (b == 0 && !m_evmVersion.hasPush0())
{
b = 1;
}
ret.bytecode.push_back(static_cast<uint8_t>(pushInstruction(b)));
ret.bytecode.resize(ret.bytecode.size() + b);
bytesRef byr(&ret.bytecode.back() + 1 - b, b);
toBigEndian(i.data(), byr);
if (b > 0)
{
ret.bytecode.resize(ret.bytecode.size() + b);
bytesRef byr(&ret.bytecode.back() + 1 - b, b);
toBigEndian(i.data(), byr);
}
break;
}
case PushTag:
@ -576,21 +582,21 @@ LinkerObject const& Assembly::assemble() const
}
case PushData:
ret.bytecode.push_back(dataRefPush);
dataRef.insert(make_pair(h256(i.data()), ret.bytecode.size()));
dataRef.insert(std::make_pair(h256(i.data()), ret.bytecode.size()));
ret.bytecode.resize(ret.bytecode.size() + bytesPerDataRef);
break;
case PushSub:
assertThrow(i.data() <= numeric_limits<size_t>::max(), AssemblyException, "");
assertThrow(i.data() <= std::numeric_limits<size_t>::max(), AssemblyException, "");
ret.bytecode.push_back(dataRefPush);
subRef.insert(make_pair(static_cast<size_t>(i.data()), ret.bytecode.size()));
subRef.insert(std::make_pair(static_cast<size_t>(i.data()), ret.bytecode.size()));
ret.bytecode.resize(ret.bytecode.size() + bytesPerDataRef);
break;
case PushSubSize:
{
assertThrow(i.data() <= numeric_limits<size_t>::max(), AssemblyException, "");
assertThrow(i.data() <= std::numeric_limits<size_t>::max(), AssemblyException, "");
auto s = subAssemblyById(static_cast<size_t>(i.data()))->assemble().bytecode.size();
i.setPushedValue(u256(s));
unsigned b = max<unsigned>(1, numberEncodingSize(s));
unsigned b = std::max<unsigned>(1, numberEncodingSize(s));
ret.bytecode.push_back(static_cast<uint8_t>(pushInstruction(b)));
ret.bytecode.resize(ret.bytecode.size() + b);
bytesRef byr(&ret.bytecode.back() + 1 - b, b);
@ -611,7 +617,7 @@ LinkerObject const& Assembly::assemble() const
break;
case PushImmutable:
ret.bytecode.push_back(static_cast<uint8_t>(Instruction::PUSH32));
// Maps keccak back to the "identifier" string of that immutable.
// Maps keccak back to the "identifier" std::string of that immutable.
ret.immutableReferences[i.data()].first = m_immutables.at(i.data());
// Record the bytecode offset of the PUSH32 argument.
ret.immutableReferences[i.data()].second.emplace_back(ret.bytecode.size());
@ -654,10 +660,10 @@ LinkerObject const& Assembly::assemble() const
case Tag:
{
assertThrow(i.data() != 0, AssemblyException, "Invalid tag position.");
assertThrow(i.splitForeignPushTag().first == numeric_limits<size_t>::max(), AssemblyException, "Foreign tag.");
assertThrow(i.splitForeignPushTag().first == std::numeric_limits<size_t>::max(), AssemblyException, "Foreign tag.");
size_t tagId = static_cast<size_t>(i.data());
assertThrow(ret.bytecode.size() < 0xffffffffL, AssemblyException, "Tag too large.");
assertThrow(m_tagPositionsInBytecode[tagId] == numeric_limits<size_t>::max(), AssemblyException, "Duplicate tag position.");
assertThrow(m_tagPositionsInBytecode[tagId] == std::numeric_limits<size_t>::max(), AssemblyException, "Duplicate tag position.");
m_tagPositionsInBytecode[tagId] = ret.bytecode.size();
ret.bytecode.push_back(static_cast<uint8_t>(Instruction::JUMPDEST));
break;
@ -679,26 +685,38 @@ LinkerObject const& Assembly::assemble() const
// Append an INVALID here to help tests find miscompilation.
ret.bytecode.push_back(static_cast<uint8_t>(Instruction::INVALID));
std::map<LinkerObject, size_t> subAssemblyOffsets;
for (auto const& [subIdPath, bytecodeOffset]: subRef)
{
LinkerObject subObject = subAssemblyById(subIdPath)->assemble();
bytesRef r(ret.bytecode.data() + bytecodeOffset, bytesPerDataRef);
toBigEndian(ret.bytecode.size(), r);
ret.append(subAssemblyById(subIdPath)->assemble());
}
// In order for de-duplication to kick in, not only must the bytecode be identical, but
// link and immutables references as well.
if (size_t* subAssemblyOffset = util::valueOrNullptr(subAssemblyOffsets, subObject))
toBigEndian(*subAssemblyOffset, r);
else
{
toBigEndian(ret.bytecode.size(), r);
subAssemblyOffsets[subObject] = ret.bytecode.size();
ret.bytecode += subObject.bytecode;
}
for (auto const& ref: subObject.linkReferences)
ret.linkReferences[ref.first + subAssemblyOffsets[subObject]] = ref.second;
}
for (auto const& i: tagRef)
{
size_t subId;
size_t tagId;
tie(subId, tagId) = i.second;
assertThrow(subId == numeric_limits<size_t>::max() || subId < m_subs.size(), AssemblyException, "Invalid sub id");
vector<size_t> const& tagPositions =
subId == numeric_limits<size_t>::max() ?
std::tie(subId, tagId) = i.second;
assertThrow(subId == std::numeric_limits<size_t>::max() || subId < m_subs.size(), AssemblyException, "Invalid sub id");
std::vector<size_t> const& tagPositions =
subId == std::numeric_limits<size_t>::max() ?
m_tagPositionsInBytecode :
m_subs[subId]->m_tagPositionsInBytecode;
assertThrow(tagId < tagPositions.size(), AssemblyException, "Reference to non-existing tag.");
size_t pos = tagPositions[tagId];
assertThrow(pos != numeric_limits<size_t>::max(), AssemblyException, "Reference to tag without position.");
assertThrow(pos != std::numeric_limits<size_t>::max(), AssemblyException, "Reference to tag without position.");
assertThrow(numberEncodingSize(pos) <= bytesPerTag, AssemblyException, "Tag too large for reserved space.");
bytesRef r(ret.bytecode.data() + i.first, bytesPerTag);
toBigEndian(pos, r);
@ -706,7 +724,7 @@ LinkerObject const& Assembly::assemble() const
for (auto const& [name, tagInfo]: m_namedTags)
{
size_t position = m_tagPositionsInBytecode.at(tagInfo.id);
optional<size_t> tagIndex;
std::optional<size_t> tagIndex;
for (auto&& [index, item]: m_items | ranges::views::enumerate)
if (item.type() == Tag && static_cast<size_t>(item.data()) == tagInfo.id)
{
@ -714,7 +732,7 @@ LinkerObject const& Assembly::assemble() const
break;
}
ret.functionDebugData[name] = {
position == numeric_limits<size_t>::max() ? nullopt : optional<size_t>{position},
position == std::numeric_limits<size_t>::max() ? std::nullopt : std::optional<size_t>{position},
tagIndex,
tagInfo.sourceID,
tagInfo.params,
@ -745,7 +763,7 @@ LinkerObject const& Assembly::assemble() const
return ret;
}
vector<size_t> Assembly::decodeSubPath(size_t _subObjectId) const
std::vector<size_t> Assembly::decodeSubPath(size_t _subObjectId) const
{
if (_subObjectId < m_subs.size())
return {_subObjectId};
@ -760,7 +778,7 @@ vector<size_t> Assembly::decodeSubPath(size_t _subObjectId) const
return subIdPathIt->first;
}
size_t Assembly::encodeSubPath(vector<size_t> const& _subPath)
size_t Assembly::encodeSubPath(std::vector<size_t> const& _subPath)
{
assertThrow(!_subPath.empty(), AssemblyException, "");
if (_subPath.size() == 1)
@ -771,7 +789,7 @@ size_t Assembly::encodeSubPath(vector<size_t> const& _subPath)
if (m_subPaths.find(_subPath) == m_subPaths.end())
{
size_t objectId = numeric_limits<size_t>::max() - m_subPaths.size();
size_t objectId = std::numeric_limits<size_t>::max() - m_subPaths.size();
assertThrow(objectId >= m_subs.size(), AssemblyException, "");
m_subPaths[_subPath] = objectId;
}
@ -781,7 +799,7 @@ size_t Assembly::encodeSubPath(vector<size_t> const& _subPath)
Assembly const* Assembly::subAssemblyById(size_t _subId) const
{
vector<size_t> subIds = decodeSubPath(_subId);
std::vector<size_t> subIds = decodeSubPath(_subId);
Assembly const* currentAssembly = this;
for (size_t currentSubId: subIds)
{

5
libevmasm/Assembly.h
View File

@ -49,7 +49,7 @@ using AssemblyPointer = std::shared_ptr<Assembly>;
class Assembly
{
public:
Assembly(bool _creation, std::string _name): m_creation(_creation), m_name(std::move(_name)) { }
Assembly(langutil::EVMVersion _evmVersion, bool _creation, std::string _name): m_evmVersion(_evmVersion), m_creation(_creation), m_name(std::move(_name)) { }
AssemblyItem newTag() { assertThrow(m_usedTags < 0xffffffff, AssemblyException, ""); return AssemblyItem(Tag, m_usedTags++); }
AssemblyItem newPushTag() { assertThrow(m_usedTags < 0xffffffff, AssemblyException, ""); return AssemblyItem(PushTag, m_usedTags++); }
@ -112,6 +112,7 @@ public:
/// Changes the source location used for each appended item.
void setSourceLocation(langutil::SourceLocation const& _location) { m_currentSourceLocation = _location; }
langutil::SourceLocation const& currentSourceLocation() const { return m_currentSourceLocation; }
langutil::EVMVersion const& evmVersion() const { return m_evmVersion; }
/// Assembles the assembly into bytecode. The assembly should not be modified after this call, since the assembled version is cached.
LinkerObject const& assemble() const;
@ -208,6 +209,8 @@ protected:
mutable LinkerObject m_assembledObject;
mutable std::vector<size_t> m_tagPositionsInBytecode;
langutil::EVMVersion m_evmVersion;
int m_deposit = 0;
/// True, if the assembly contains contract creation code.
bool const m_creation = false;

97
libevmasm/AssemblyItem.cpp
View File

@ -30,7 +30,7 @@
#include <fstream>
#include <limits>
using namespace std;
using namespace std::literals;
using namespace solidity;
using namespace solidity::evmasm;
using namespace solidity::langutil;
@ -40,10 +40,10 @@ static_assert(sizeof(size_t) <= 8, "size_t must be at most 64-bits wide");
namespace
{
string toStringInHex(u256 _value)
std::string toStringInHex(u256 _value)
{
std::stringstream hexStr;
hexStr << std::uppercase << hex << _value;
hexStr << std::uppercase << std::hex << _value;
return hexStr.str();
}
@ -60,21 +60,21 @@ AssemblyItem AssemblyItem::toSubAssemblyTag(size_t _subId) const
return r;
}
pair<size_t, size_t> AssemblyItem::splitForeignPushTag() const
std::pair<size_t, size_t> AssemblyItem::splitForeignPushTag() const
{
assertThrow(m_type == PushTag || m_type == Tag, util::Exception, "");
u256 combined = u256(data());
size_t subId = static_cast<size_t>((combined >> 64) - 1);
size_t tag = static_cast<size_t>(combined & 0xffffffffffffffffULL);
return make_pair(subId, tag);
return std::make_pair(subId, tag);
}
pair<string, string> AssemblyItem::nameAndData() const
std::pair<std::string, std::string> AssemblyItem::nameAndData(langutil::EVMVersion _evmVersion) const
{
switch (type())
{
case Operation:
return {instructionInfo(instruction()).name, m_data != nullptr ? toStringInHex(*m_data) : ""};
return {instructionInfo(instruction(), _evmVersion).name, m_data != nullptr ? toStringInHex(*m_data) : ""};
case Push:
return {"PUSH", toStringInHex(data())};
case PushTag:
@ -111,7 +111,7 @@ void AssemblyItem::setPushTagSubIdAndTag(size_t _subId, size_t _tag)
{
assertThrow(m_type == PushTag || m_type == Tag, util::Exception, "");
u256 data = _tag;
if (_subId != numeric_limits<size_t>::max())
if (_subId != std::numeric_limits<size_t>::max())
data |= (u256(_subId) + 1) << 64;
setData(data);
}
@ -124,7 +124,7 @@ size_t AssemblyItem::bytesRequired(size_t _addressLength, Precision _precision)
case Tag: // 1 byte for the JUMPDEST
return 1;
case Push:
return 1 + max<size_t>(1, numberEncodingSize(data()));
return 1 + std::max<size_t>(1, numberEncodingSize(data()));
case PushSubSize:
case PushProgramSize:
return 1 + 4; // worst case: a 16MB program
@ -168,9 +168,11 @@ size_t AssemblyItem::bytesRequired(size_t _addressLength, Precision _precision)
size_t AssemblyItem::arguments() const
{
if (type() == Operation)
return static_cast<size_t>(instructionInfo(instruction()).args);
// The latest EVMVersion is used here, since the InstructionInfo is assumed to be
// the same across all EVM versions except for the instruction name.
return static_cast<size_t>(instructionInfo(instruction(), EVMVersion()).args);
else if (type() == VerbatimBytecode)
return get<0>(*m_verbatimBytecode);
return std::get<0>(*m_verbatimBytecode);
else if (type() == AssignImmutable)
return 2;
else
@ -182,7 +184,9 @@ size_t AssemblyItem::returnValues() const
switch (m_type)
{
case Operation:
return static_cast<size_t>(instructionInfo(instruction()).ret);
// The latest EVMVersion is used here, since the InstructionInfo is assumed to be
// the same across all EVM versions except for the instruction name.
return static_cast<size_t>(instructionInfo(instruction(), EVMVersion()).ret);
case Push:
case PushTag:
case PushData:
@ -196,7 +200,7 @@ size_t AssemblyItem::returnValues() const
case Tag:
return 0;
case VerbatimBytecode:
return get<1>(*m_verbatimBytecode);
return std::get<1>(*m_verbatimBytecode);
default:
break;
}
@ -229,7 +233,7 @@ bool AssemblyItem::canBeFunctional() const
return false;
}
string AssemblyItem::getJumpTypeAsString() const
std::string AssemblyItem::getJumpTypeAsString() const
{
switch (m_jumpType)
{
@ -243,15 +247,15 @@ string AssemblyItem::getJumpTypeAsString() const
}
}
string AssemblyItem::toAssemblyText(Assembly const& _assembly) const
std::string AssemblyItem::toAssemblyText(Assembly const& _assembly) const
{
string text;
std::string text;
switch (type())
{
case Operation:
{
assertThrow(isValidInstruction(instruction()), AssemblyException, "Invalid instruction.");
text = util::toLower(instructionInfo(instruction()).name);
text = util::toLower(instructionInfo(instruction(), _assembly.evmVersion()).name);
break;
}
case Push:
@ -261,26 +265,26 @@ string AssemblyItem::toAssemblyText(Assembly const& _assembly) const
{
size_t sub{0};
size_t tag{0};
tie(sub, tag) = splitForeignPushTag();
if (sub == numeric_limits<size_t>::max())
text = string("tag_") + to_string(tag);
std::tie(sub, tag) = splitForeignPushTag();
if (sub == std::numeric_limits<size_t>::max())
text = std::string("tag_") + std::to_string(tag);
else
text = string("tag_") + to_string(sub) + "_" + to_string(tag);
text = std::string("tag_") + std::to_string(sub) + "_" + std::to_string(tag);
break;
}
case Tag:
assertThrow(data() < 0x10000, AssemblyException, "Declaration of sub-assembly tag.");
text = string("tag_") + to_string(static_cast<size_t>(data())) + ":";
text = std::string("tag_") + std::to_string(static_cast<size_t>(data())) + ":";
break;
case PushData:
text = string("data_") + toHex(data());
text = std::string("data_") + toHex(data());
break;
case PushSub:
case PushSubSize:
{
vector<string> subPathComponents;
std::vector<std::string> subPathComponents;
for (size_t subPathComponentId: _assembly.decodeSubPath(static_cast<size_t>(data())))
subPathComponents.emplace_back("sub_" + to_string(subPathComponentId));
subPathComponents.emplace_back("sub_" + std::to_string(subPathComponentId));
text =
(type() == PushSub ? "dataOffset"s : "dataSize"s) +
"(" +
@ -289,25 +293,25 @@ string AssemblyItem::toAssemblyText(Assembly const& _assembly) const
break;
}
case PushProgramSize:
text = string("bytecodeSize");
text = std::string("bytecodeSize");
break;
case PushLibraryAddress:
text = string("linkerSymbol(\"") + toHex(data()) + string("\")");
text = std::string("linkerSymbol(\"") + toHex(data()) + std::string("\")");
break;
case PushDeployTimeAddress:
text = string("deployTimeAddress()");
text = std::string("deployTimeAddress()");
break;
case PushImmutable:
text = string("immutable(\"") + "0x" + util::toHex(toCompactBigEndian(data(), 1)) + "\")";
text = std::string("immutable(\"") + "0x" + util::toHex(toCompactBigEndian(data(), 1)) + "\")";
break;
case AssignImmutable:
text = string("assignImmutable(\"") + "0x" + util::toHex(toCompactBigEndian(data(), 1)) + "\")";
text = std::string("assignImmutable(\"") + "0x" + util::toHex(toCompactBigEndian(data(), 1)) + "\")";
break;
case UndefinedItem:
assertThrow(false, AssemblyException, "Invalid assembly item.");
break;
case VerbatimBytecode:
text = string("verbatimbytecode_") + util::toHex(get<2>(*m_verbatimBytecode));
text = std::string("verbatimbytecode_") + util::toHex(std::get<2>(*m_verbatimBytecode));
break;
default:
assertThrow(false, InvalidOpcode, "");
@ -323,22 +327,23 @@ string AssemblyItem::toAssemblyText(Assembly const& _assembly) const
return text;
}
ostream& solidity::evmasm::operator<<(ostream& _out, AssemblyItem const& _item)
// Note: This method is exclusively used for debugging.
std::ostream& solidity::evmasm::operator<<(std::ostream& _out, AssemblyItem const& _item)
{
switch (_item.type())
{
case Operation:
_out << " " << instructionInfo(_item.instruction()).name;
_out << " " << instructionInfo(_item.instruction(), EVMVersion()).name;
if (_item.instruction() == Instruction::JUMP || _item.instruction() == Instruction::JUMPI)
_out << "\t" << _item.getJumpTypeAsString();
break;
case Push:
_out << " PUSH " << hex << _item.data() << dec;
_out << " PUSH " << std::hex << _item.data() << std::dec;
break;
case PushTag:
{
size_t subId = _item.splitForeignPushTag().first;
if (subId == numeric_limits<size_t>::max())
if (subId == std::numeric_limits<size_t>::max())
_out << " PushTag " << _item.splitForeignPushTag().second;
else
_out << " PushTag " << subId << ":" << _item.splitForeignPushTag().second;
@ -348,20 +353,20 @@ ostream& solidity::evmasm::operator<<(ostream& _out, AssemblyItem const& _item)
_out << " Tag " << _item.data();
break;
case PushData:
_out << " PushData " << hex << static_cast<unsigned>(_item.data()) << dec;
_out << " PushData " << std::hex << static_cast<unsigned>(_item.data()) << std::dec;
break;
case PushSub:
_out << " PushSub " << hex << static_cast<size_t>(_item.data()) << dec;
_out << " PushSub " << std::hex << static_cast<size_t>(_item.data()) << std::dec;
break;
case PushSubSize:
_out << " PushSubSize " << hex << static_cast<size_t>(_item.data()) << dec;
_out << " PushSubSize " << std::hex << static_cast<size_t>(_item.data()) << std::dec;
break;
case PushProgramSize:
_out << " PushProgramSize";
break;
case PushLibraryAddress:
{
string hash(util::h256((_item.data())).hex());
std::string hash(util::h256((_item.data())).hex());
_out << " PushLibraryAddress " << hash.substr(0, 8) + "..." + hash.substr(hash.length() - 8);
break;
}
@ -408,10 +413,10 @@ size_t AssemblyItem::opcodeCount() const noexcept
std::string AssemblyItem::computeSourceMapping(
AssemblyItems const& _items,
map<string, unsigned> const& _sourceIndicesMap
std::map<std::string, unsigned> const& _sourceIndicesMap
)
{
string ret;
std::string ret;
int prevStart = -1;
int prevLength = -1;
@ -460,17 +465,17 @@ std::string AssemblyItem::computeSourceMapping(
if (components-- > 0)
{
if (location.start != prevStart)
ret += to_string(location.start);
ret += std::to_string(location.start);
if (components-- > 0)
{
ret += ':';
if (length != prevLength)
ret += to_string(length);
ret += std::to_string(length);
if (components-- > 0)
{
ret += ':';
if (sourceIndex != prevSourceIndex)
ret += to_string(sourceIndex);
ret += std::to_string(sourceIndex);
if (components-- > 0)
{
ret += ':';
@ -480,7 +485,7 @@ std::string AssemblyItem::computeSourceMapping(
{
ret += ':';
if (modifierDepth != prevModifierDepth)
ret += to_string(modifierDepth);
ret += std::to_string(modifierDepth);
}
}
}
@ -488,7 +493,7 @@ std::string AssemblyItem::computeSourceMapping(
}
if (item.opcodeCount() > 1)
ret += string(item.opcodeCount() - 1, ';');
ret += std::string(item.opcodeCount() - 1, ';');
prevStart = location.start;
prevLength = length;

3
libevmasm/AssemblyItem.h
View File

@ -108,10 +108,11 @@ public:
/// This function is used in `Assembly::assemblyJSON`.
/// It returns the name & data of the current assembly item.
/// @param _evmVersion the EVM version.
/// @returns a pair, where the first element is the json-assembly
/// item name, where second element is the string representation
/// of it's data.
std::pair<std::string, std::string> nameAndData() const;
std::pair<std::string, std::string> nameAndData(langutil::EVMVersion _evmVersion) const;
bytes const& verbatimData() const { assertThrow(m_type == VerbatimBytecode, util::Exception, ""); return std::get<2>(*m_verbatimBytecode); }

9
libevmasm/BlockDeduplicator.cpp
View File

@ -30,7 +30,6 @@
#include <functional>
#include <set>
using namespace std;
using namespace solidity;
using namespace solidity::evmasm;
@ -49,7 +48,7 @@ bool BlockDeduplicator::deduplicate()
)
return false;
function<bool(size_t, size_t)> comparator = [&](size_t _i, size_t _j)
std::function<bool(size_t, size_t)> comparator = [&](size_t _i, size_t _j)
{
if (_i == _j)
return false;
@ -81,7 +80,7 @@ bool BlockDeduplicator::deduplicate()
for (; ; ++iterations)
{
//@todo this should probably be optimized.
set<size_t, function<bool(size_t, size_t)>> blocksSeen(comparator);
std::set<size_t, std::function<bool(size_t, size_t)>> blocksSeen(comparator);
for (size_t i = 0; i < m_items.size(); ++i)
{
if (m_items.at(i).type() != Tag)
@ -101,7 +100,7 @@ bool BlockDeduplicator::deduplicate()
bool BlockDeduplicator::applyTagReplacement(
AssemblyItems& _items,
map<u256, u256> const& _replacements,
std::map<u256, u256> const& _replacements,
size_t _subId
)
{
@ -111,7 +110,7 @@ bool BlockDeduplicator::applyTagReplacement(
{
size_t subId;
size_t tagId;
tie(subId, tagId) = item.splitForeignPushTag();
std::tie(subId, tagId) = item.splitForeignPushTag();
if (subId != _subId)
continue;
auto it = _replacements.find(tagId);

33
libevmasm/CommonSubexpressionEliminator.cpp
View File

@ -30,12 +30,11 @@
#include <range/v3/view/reverse.hpp>
using namespace std;
using namespace solidity;
using namespace solidity::evmasm;
using namespace solidity::langutil;
vector<AssemblyItem> CommonSubexpressionEliminator::getOptimizedItems()
std::vector<AssemblyItem> CommonSubexpressionEliminator::getOptimizedItems()
{
optimizeBreakingItem();
@ -52,11 +51,11 @@ vector<AssemblyItem> CommonSubexpressionEliminator::getOptimizedItems()
m_state = std::move(nextState);
});
map<int, Id> initialStackContents;
map<int, Id> targetStackContents;
std::map<int, Id> initialStackContents;
std::map<int, Id> targetStackContents;
int minHeight = m_state.stackHeight() + 1;
if (!m_state.stackElements().empty())
minHeight = min(minHeight, m_state.stackElements().begin()->first);
minHeight = std::min(minHeight, m_state.stackElements().begin()->first);
for (int height = minHeight; height <= m_initialState.stackHeight(); ++height)
initialStackContents[height] = m_initialState.stackElement(height, SourceLocation());
for (int height = minHeight; height <= m_state.stackHeight(); ++height)
@ -125,19 +124,19 @@ void CommonSubexpressionEliminator::optimizeBreakingItem()
CSECodeGenerator::CSECodeGenerator(
ExpressionClasses& _expressionClasses,
vector<CSECodeGenerator::StoreOperation> const& _storeOperations
std::vector<CSECodeGenerator::StoreOperation> const& _storeOperations
):
m_expressionClasses(_expressionClasses)
{
for (auto const& store: _storeOperations)
m_storeOperations[make_pair(store.target, store.slot)].push_back(store);
m_storeOperations[std::make_pair(store.target, store.slot)].push_back(store);
}
AssemblyItems CSECodeGenerator::generateCode(
unsigned _initialSequenceNumber,
int _initialStackHeight,
map<int, Id> const& _initialStack,
map<int, Id> const& _targetStackContents
std::map<int, Id> const& _initialStack,
std::map<int, Id> const& _targetStackContents
)
{
m_stackHeight = _initialStackHeight;
@ -156,7 +155,7 @@ AssemblyItems CSECodeGenerator::generateCode(
}
// store all needed sequenced expressions
set<pair<unsigned, Id>> sequencedExpressions;
std::set<std::pair<unsigned, Id>> sequencedExpressions;
for (auto const& p: m_neededBy)
for (auto id: {p.first, p.second})
if (unsigned seqNr = m_expressionClasses.representative(id).sequenceNumber)
@ -165,7 +164,7 @@ AssemblyItems CSECodeGenerator::generateCode(
// @todo quick fix for now. Proper fix needs to choose representative with higher
// sequence number during dependency analysis.
assertThrow(seqNr >= _initialSequenceNumber, StackTooDeepException, util::stackTooDeepString);
sequencedExpressions.insert(make_pair(seqNr, id));
sequencedExpressions.insert(std::make_pair(seqNr, id));
}
// Perform all operations on storage and memory in order, if they are needed.
@ -230,7 +229,7 @@ void CSECodeGenerator::addDependencies(Id _c)
for (Id argument: expr.arguments)
{
addDependencies(argument);
m_neededBy.insert(make_pair(argument, _c));
m_neededBy.insert(std::make_pair(argument, _c));
}
if (expr.item && expr.item->type() == Operation && (
expr.item->instruction() == Instruction::SLOAD ||
@ -294,7 +293,7 @@ void CSECodeGenerator::addDependencies(Id _c)
if (it->sequenceNumber < expr.sequenceNumber)
latestStore = it->expression;
addDependencies(latestStore);
m_neededBy.insert(make_pair(latestStore, _c));
m_neededBy.insert(std::make_pair(latestStore, _c));
}
}
}
@ -331,7 +330,7 @@ void CSECodeGenerator::generateClassElement(Id _c, bool _allowSequenced)
OptimizerException,
"Undefined item requested but not available."
);
vector<Id> const& arguments = expr.arguments;
std::vector<Id> const& arguments = expr.arguments;
for (Id arg: arguments | ranges::views::reverse)
generateClassElement(arg);
@ -406,7 +405,7 @@ void CSECodeGenerator::generateClassElement(Id _c, bool _allowSequenced)
m_stack.erase(m_stackHeight - static_cast<int>(i));
}
appendItem(*expr.item);
if (expr.item->type() != Operation || instructionInfo(expr.item->instruction()).ret == 1)
if (expr.item->type() != Operation || instructionInfo(expr.item->instruction(), EVMVersion()).ret == 1)
{
m_stack[m_stackHeight] = _c;
m_classPositions[_c].insert(m_stackHeight);
@ -414,7 +413,7 @@ void CSECodeGenerator::generateClassElement(Id _c, bool _allowSequenced)
else
{
assertThrow(
instructionInfo(expr.item->instruction()).ret == 0,
instructionInfo(expr.item->instruction(), EVMVersion()).ret == 0,
OptimizerException,
"Invalid number of return values."
);
@ -495,7 +494,7 @@ void CSECodeGenerator::appendOrRemoveSwap(int _fromPosition, SourceLocation cons
m_classPositions[m_stack[m_stackHeight]].insert(_fromPosition);
m_classPositions[m_stack[_fromPosition]].erase(_fromPosition);
m_classPositions[m_stack[_fromPosition]].insert(m_stackHeight);
swap(m_stack[m_stackHeight], m_stack[_fromPosition]);
std::swap(m_stack[m_stackHeight], m_stack[_fromPosition]);
}
if (m_generatedItems.size() >= 2 &&
SemanticInformation::isSwapInstruction(m_generatedItems.back()) &&

21
libevmasm/ConstantOptimiser.cpp
View File

@ -24,7 +24,6 @@
#include <libevmasm/Assembly.h>
#include <libevmasm/GasMeter.h>
using namespace std;
using namespace solidity;
using namespace solidity::evmasm;
@ -39,11 +38,11 @@ unsigned ConstantOptimisationMethod::optimiseConstants(
AssemblyItems& _items = _assembly.items();
unsigned optimisations = 0;
map<AssemblyItem, size_t> pushes;
std::map<AssemblyItem, size_t> pushes;
for (AssemblyItem const& item: _items)
if (item.type() == Push)
pushes[item]++;
map<u256, AssemblyItems> pendingReplacements;
std::map<u256, AssemblyItems> pendingReplacements;
for (auto it: pushes)
{
AssemblyItem const& item = it.first;
@ -79,18 +78,18 @@ unsigned ConstantOptimisationMethod::optimiseConstants(
return optimisations;
}
bigint ConstantOptimisationMethod::simpleRunGas(AssemblyItems const& _items)
bigint ConstantOptimisationMethod::simpleRunGas(AssemblyItems const& _items, langutil::EVMVersion _evmVersion)
{
bigint gas = 0;
for (AssemblyItem const& item: _items)
if (item.type() == Push)
gas += GasMeter::runGas(Instruction::PUSH1);
gas += GasMeter::runGas(Instruction::PUSH1, _evmVersion);
else if (item.type() == Operation)
{
if (item.instruction() == Instruction::EXP)
gas += GasCosts::expGas;
else
gas += GasMeter::runGas(item.instruction());
gas += GasMeter::runGas(item.instruction(), _evmVersion);
}
return gas;
}
@ -108,7 +107,7 @@ size_t ConstantOptimisationMethod::bytesRequired(AssemblyItems const& _items)
void ConstantOptimisationMethod::replaceConstants(
AssemblyItems& _items,
map<u256, AssemblyItems> const& _replacements
std::map<u256, AssemblyItems> const& _replacements
)
{
AssemblyItems replaced;
@ -131,7 +130,7 @@ void ConstantOptimisationMethod::replaceConstants(
bigint LiteralMethod::gasNeeded() const
{
return combineGas(
simpleRunGas({Instruction::PUSH1}),
simpleRunGas({Instruction::PUSH1}, m_params.evmVersion),
// PUSHX plus data
(m_params.isCreation ? GasCosts::txDataNonZeroGas(m_params.evmVersion) : GasCosts::createDataGas) + dataGas(toCompactBigEndian(m_value, 1)),
0
@ -142,7 +141,7 @@ bigint CodeCopyMethod::gasNeeded() const
{
return combineGas(
// Run gas: we ignore memory increase costs
simpleRunGas(copyRoutine()) + GasCosts::copyGas,
simpleRunGas(copyRoutine(), m_params.evmVersion) + GasCosts::copyGas,
// Data gas for copy routines: Some bytes are zero, but we ignore them.
bytesRequired(copyRoutine()) * (m_params.isCreation ? GasCosts::txDataNonZeroGas(m_params.evmVersion) : GasCosts::createDataGas),
// Data gas for data itself
@ -255,7 +254,7 @@ AssemblyItems ComputeMethod::findRepresentation(u256 const& _value)
bool ComputeMethod::checkRepresentation(u256 const& _value, AssemblyItems const& _routine) const
{
// This is a tiny EVM that can only evaluate some instructions.
vector<u256> stack;
std::vector<u256> stack;
for (AssemblyItem const& item: _routine)
{
switch (item.type())
@ -322,7 +321,7 @@ bigint ComputeMethod::gasNeeded(AssemblyItems const& _routine) const
{
auto numExps = static_cast<size_t>(count(_routine.begin(), _routine.end(), Instruction::EXP));
return combineGas(
simpleRunGas(_routine) + numExps * (GasCosts::expGas + GasCosts::expByteGas(m_params.evmVersion)),
simpleRunGas(_routine, m_params.evmVersion) + numExps * (GasCosts::expGas + GasCosts::expByteGas(m_params.evmVersion)),
// Data gas for routine: Some bytes are zero, but we ignore them.
bytesRequired(_routine) * (m_params.isCreation ? GasCosts::txDataNonZeroGas(m_params.evmVersion) : GasCosts::createDataGas),
0

2
libevmasm/ConstantOptimiser.h
View File

@ -76,7 +76,7 @@ protected:
protected:
/// @returns the run gas for the given items ignoring special gas costs
static bigint simpleRunGas(AssemblyItems const& _items);
static bigint simpleRunGas(AssemblyItems const& _items, langutil::EVMVersion _evmVersion);
/// @returns the gas needed to store the given data literally
bigint dataGas(bytes const& _data) const;
static size_t bytesRequired(AssemblyItems const& _items);

25
libevmasm/ControlFlowGraph.cpp
View File

@ -31,7 +31,6 @@
#include <libevmasm/SemanticInformation.h>
#include <libevmasm/KnownState.h>
using namespace std;
using namespace solidity;
using namespace solidity::evmasm;
@ -64,7 +63,7 @@ void ControlFlowGraph::findLargestTag()
{
// Assert that it can be converted.
BlockId(item.data());
m_lastUsedId = max(unsigned(item.data()), m_lastUsedId);
m_lastUsedId = std::max(unsigned(item.data()), m_lastUsedId);
}
}
@ -111,7 +110,7 @@ void ControlFlowGraph::splitBlocks()
void ControlFlowGraph::resolveNextLinks()
{
map<unsigned, BlockId> blockByBeginPos;
std::map<unsigned, BlockId> blockByBeginPos;
for (auto const& idAndBlock: m_blocks)
if (idAndBlock.second.begin != idAndBlock.second.end)
blockByBeginPos[idAndBlock.second.begin] = idAndBlock.first;
@ -138,8 +137,8 @@ void ControlFlowGraph::resolveNextLinks()
void ControlFlowGraph::removeUnusedBlocks()
{
vector<BlockId> blocksToProcess{BlockId::initial()};
set<BlockId> neededBlocks{BlockId::initial()};
std::vector<BlockId> blocksToProcess{BlockId::initial()};
std::set<BlockId> neededBlocks{BlockId::initial()};
while (!blocksToProcess.empty())
{
BasicBlock const& block = m_blocks.at(blocksToProcess.back());
@ -219,16 +218,16 @@ void ControlFlowGraph::gatherKnowledge()
{
// @todo actually we know that memory is filled with zeros at the beginning,
// we could make use of that.
KnownStatePointer emptyState = make_shared<KnownState>();
KnownStatePointer emptyState = std::make_shared<KnownState>();
bool unknownJumpEncountered = false;
struct WorkQueueItem {
BlockId blockId;
KnownStatePointer state;
set<BlockId> blocksSeen;
std::set<BlockId> blocksSeen;
};
vector<WorkQueueItem> workQueue{WorkQueueItem{BlockId::initial(), emptyState->copy(), set<BlockId>()}};
std::vector<WorkQueueItem> workQueue{WorkQueueItem{BlockId::initial(), emptyState->copy(), std::set<BlockId>()}};
auto addWorkQueueItem = [&](WorkQueueItem const& _currentItem, BlockId _to, KnownStatePointer const& _state)
{
WorkQueueItem item;
@ -275,7 +274,7 @@ void ControlFlowGraph::gatherKnowledge()
assertThrow(block.begin <= pc && pc == block.end - 1, OptimizerException, "");
//@todo in the case of JUMPI, add knowledge about the condition to the state
// (for both values of the condition)
set<u256> tags = state->tagsInExpression(
std::set<u256> tags = state->tagsInExpression(
state->stackElement(state->stackHeight(), langutil::SourceLocation{})
);
state->feedItem(m_items.at(pc++));
@ -289,7 +288,7 @@ void ControlFlowGraph::gatherKnowledge()
unknownJumpEncountered = true;
for (auto const& it: m_blocks)
if (it.second.begin < it.second.end && m_items[it.second.begin].type() == Tag)
workQueue.push_back(WorkQueueItem{it.first, emptyState->copy(), set<BlockId>()});
workQueue.push_back(WorkQueueItem{it.first, emptyState->copy(), std::set<BlockId>()});
}
}
else
@ -321,16 +320,16 @@ void ControlFlowGraph::gatherKnowledge()
BasicBlocks ControlFlowGraph::rebuildCode()
{
map<BlockId, unsigned> pushes;
std::map<BlockId, unsigned> pushes;
for (auto& idAndBlock: m_blocks)
for (BlockId ref: idAndBlock.second.pushedTags)
if (m_blocks.count(ref))
pushes[ref]++;
set<BlockId> blocksToAdd;
std::set<BlockId> blocksToAdd;
for (auto it: m_blocks)
blocksToAdd.insert(it.first);
set<BlockId> blocksAdded;
std::set<BlockId> blocksAdded;
BasicBlocks blocks;
for (

14
libevmasm/Disassemble.cpp
View File

@ -22,7 +22,6 @@
#include <libsolutil/CommonIO.h>
#include <functional>
using namespace std;
using namespace solidity;
using namespace solidity::util;
using namespace solidity::evmasm;
@ -30,7 +29,8 @@ using namespace solidity::evmasm;
void solidity::evmasm::eachInstruction(
bytes const& _mem,
function<void(Instruction,u256 const&)> const& _onInstruction
langutil::EVMVersion _evmVersion,
std::function<void(Instruction,u256 const&)> const& _onInstruction
)
{
for (auto it = _mem.begin(); it < _mem.end(); ++it)
@ -38,7 +38,7 @@ void solidity::evmasm::eachInstruction(
Instruction const instr{*it};
int additional = 0;
if (isValidInstruction(instr))
additional = instructionInfo(instr).additional;
additional = instructionInfo(instr, _evmVersion).additional;
u256 data{};
@ -57,15 +57,15 @@ void solidity::evmasm::eachInstruction(
}
}
string solidity::evmasm::disassemble(bytes const& _mem, string const& _delimiter)
std::string solidity::evmasm::disassemble(bytes const& _mem, langutil::EVMVersion _evmVersion, std::string const& _delimiter)
{
stringstream ret;
eachInstruction(_mem, [&](Instruction _instr, u256 const& _data) {
std::stringstream ret;
eachInstruction(_mem, _evmVersion, [&](Instruction _instr, u256 const& _data) {
if (!isValidInstruction(_instr))
ret << "0x" << std::uppercase << std::hex << static_cast<int>(_instr) << _delimiter;
else
{
InstructionInfo info = instructionInfo(_instr);
InstructionInfo info = instructionInfo(_instr, _evmVersion);
ret << info.name;
if (info.additional)
ret << " 0x" << std::uppercase << std::hex << _data;

4
libevmasm/Disassemble.h
View File

@ -30,9 +30,9 @@ namespace solidity::evmasm
{
/// Iterate through EVM code and call a function on each instruction.
void eachInstruction(bytes const& _mem, std::function<void(Instruction, u256 const&)> const& _onInstruction);
void eachInstruction(bytes const& _mem, langutil::EVMVersion _evmVersion, std::function<void(Instruction, u256 const&)> const& _onInstruction);
/// Convert from EVM code to simple EVM assembly language.
std::string disassemble(bytes const& _mem, std::string const& _delimiter = " ");
std::string disassemble(bytes const& _mem, langutil::EVMVersion _evmVersion, std::string const& _delimiter = " ");
}

29
libevmasm/ExpressionClasses.cpp
View File

@ -34,7 +34,6 @@
#include <limits>
#include <tuple>
using namespace std;
using namespace solidity;
using namespace solidity::evmasm;
using namespace solidity::langutil;
@ -58,10 +57,10 @@ bool ExpressionClasses::Expression::operator==(ExpressionClasses::Expression con
std::tie(_other.item->data(), _other.arguments, _other.sequenceNumber);
}
std::size_t ExpressionClasses::Expression::ExpressionHash::operator()(Expression const& _expression) const
size_t ExpressionClasses::Expression::ExpressionHash::operator()(Expression const& _expression) const
{
assertThrow(!!_expression.item, OptimizerException, "");
std::size_t seed = 0;
size_t seed = 0;
auto type = _expression.item->type();
boost::hash_combine(seed, type);
@ -171,7 +170,7 @@ bool ExpressionClasses::knownNonZero(Id _c)
u256 const* ExpressionClasses::knownConstant(Id _c)
{
map<unsigned, Expression const*> matchGroups;
std::map<unsigned, Expression const*> matchGroups;
Pattern constant(Push);
constant.setMatchGroup(1, matchGroups);
if (!constant.matches(representative(_c), *this))
@ -181,15 +180,15 @@ u256 const* ExpressionClasses::knownConstant(Id _c)
AssemblyItem const* ExpressionClasses::storeItem(AssemblyItem const& _item)
{
m_spareAssemblyItems.push_back(make_shared<AssemblyItem>(_item));
m_spareAssemblyItems.push_back(std::make_shared<AssemblyItem>(_item));
return m_spareAssemblyItems.back().get();
}
string ExpressionClasses::fullDAGToString(ExpressionClasses::Id _id) const
std::string ExpressionClasses::fullDAGToString(ExpressionClasses::Id _id) const
{
Expression const& expr = representative(_id);
stringstream str;
str << dec << expr.id << ":";
std::stringstream str;
str << std::dec << expr.id << ":";
if (expr.item)
{
str << *expr.item << "(";
@ -212,25 +211,25 @@ ExpressionClasses::Id ExpressionClasses::tryToSimplify(Expression const& _expr)
_expr.item->type() != Operation ||
!SemanticInformation::isDeterministic(*_expr.item)
)
return numeric_limits<unsigned>::max();
return std::numeric_limits<unsigned>::max();
if (auto match = rules.findFirstMatch(_expr, *this))
{
// Debug info
if (false)
{
cout << "Simplifying " << *_expr.item << "(";
std::cout << "Simplifying " << *_expr.item << "(";
for (Id arg: _expr.arguments)
cout << fullDAGToString(arg) << ", ";
cout << ")" << endl;
cout << "with rule " << match->pattern.toString() << endl;
cout << "to " << match->action().toString() << endl;
std::cout << fullDAGToString(arg) << ", ";
std::cout << ")" << std::endl;
std::cout << "with rule " << match->pattern.toString() << std::endl;
std::cout << "to " << match->action().toString() << std::endl;
}
return rebuildExpression(ExpressionTemplate(match->action(), _expr.item->location()));
}
return numeric_limits<unsigned>::max();
return std::numeric_limits<unsigned>::max();
}
ExpressionClasses::Id ExpressionClasses::rebuildExpression(ExpressionTemplate const& _template)

33
libevmasm/GasMeter.cpp
View File

@ -20,7 +20,6 @@
#include <libevmasm/KnownState.h>
using namespace std;
using namespace solidity;
using namespace solidity::util;
using namespace solidity::evmasm;
@ -32,7 +31,7 @@ GasMeter::GasConsumption& GasMeter::GasConsumption::operator+=(GasConsumption co
if (isInfinite)
return *this;
bigint v = bigint(value) + _other.value;
if (v > numeric_limits<u256>::max())
if (v > std::numeric_limits<u256>::max())
*this = infinite();
else
value = u256(v);
@ -45,6 +44,12 @@ GasMeter::GasConsumption GasMeter::estimateMax(AssemblyItem const& _item, bool _
switch (_item.type())
{
case Push:
if (m_evmVersion.hasPush0() && _item.data() == 0)
{
gas = runGas(Instruction::PUSH0, m_evmVersion);
break;
}
[[fallthrough]];
case PushTag:
case PushData:
case PushSub:
@ -52,10 +57,10 @@ GasMeter::GasConsumption GasMeter::estimateMax(AssemblyItem const& _item, bool _
case PushProgramSize:
case PushLibraryAddress:
case PushDeployTimeAddress:
gas = runGas(Instruction::PUSH1);
gas = runGas(Instruction::PUSH1, m_evmVersion);
break;
case Tag:
gas = runGas(Instruction::JUMPDEST);
gas = runGas(Instruction::JUMPDEST, m_evmVersion);
break;
case Operation:
{
@ -80,19 +85,19 @@ GasMeter::GasConsumption GasMeter::estimateMax(AssemblyItem const& _item, bool _
break;
case Instruction::RETURN:
case Instruction::REVERT:
gas = runGas(_item.instruction());
gas = runGas(_item.instruction(), m_evmVersion);
gas += memoryGas(0, -1);
break;
case Instruction::MLOAD:
case Instruction::MSTORE:
gas = runGas(_item.instruction());
gas = runGas(_item.instruction(), m_evmVersion);
gas += memoryGas(classes.find(Instruction::ADD, {
m_state->relativeStackElement(0),
classes.find(AssemblyItem(32))
}));
break;
case Instruction::MSTORE8:
gas = runGas(_item.instruction());
gas = runGas(_item.instruction(), m_evmVersion);
gas += memoryGas(classes.find(Instruction::ADD, {
m_state->relativeStackElement(0),
classes.find(AssemblyItem(1))
@ -106,7 +111,7 @@ GasMeter::GasConsumption GasMeter::estimateMax(AssemblyItem const& _item, bool _
case Instruction::CALLDATACOPY:
case Instruction::CODECOPY:
case Instruction::RETURNDATACOPY:
gas = runGas(_item.instruction());
gas = runGas(_item.instruction(), m_evmVersion);
gas += memoryGas(0, -2);
gas += wordGas(GasCosts::copyGas, m_state->relativeStackElement(-2));
break;
@ -195,13 +200,13 @@ GasMeter::GasConsumption GasMeter::estimateMax(AssemblyItem const& _item, bool _
gas = GasCosts::balanceGas(m_evmVersion);
break;
case Instruction::CHAINID:
gas = runGas(Instruction::CHAINID);
gas = runGas(Instruction::CHAINID, m_evmVersion);
break;
case Instruction::SELFBALANCE:
gas = runGas(Instruction::SELFBALANCE);
gas = runGas(Instruction::SELFBALANCE, m_evmVersion);
break;
default:
gas = runGas(_item.instruction());
gas = runGas(_item.instruction(), m_evmVersion);
break;
}
break;
@ -252,12 +257,12 @@ GasMeter::GasConsumption GasMeter::memoryGas(int _stackPosOffset, int _stackPosS
}));
}
unsigned GasMeter::runGas(Instruction _instruction)
unsigned GasMeter::runGas(Instruction _instruction, langutil::EVMVersion _evmVersion)
{
if (_instruction == Instruction::JUMPDEST)
return 1;
switch (instructionInfo(_instruction).gasPriceTier)
switch (instructionInfo(_instruction, _evmVersion).gasPriceTier)
{
case Tier::Zero: return GasCosts::tier0Gas;
case Tier::Base: return GasCosts::tier1Gas;
@ -268,7 +273,7 @@ unsigned GasMeter::runGas(Instruction _instruction)
case Tier::Ext: return GasCosts::tier6Gas;
default: break;
}
assertThrow(false, OptimizerException, "Invalid gas tier for instruction " + instructionInfo(_instruction).name);
assertThrow(false, OptimizerException, "Invalid gas tier for instruction " + instructionInfo(_instruction, _evmVersion).name);
return 0;
}

3
libevmasm/GasMeter.h
View File

@ -221,7 +221,7 @@ public:
/// @returns gas costs for simple instructions with constant gas costs (that do not
/// change with EVM versions)
static unsigned runGas(Instruction _instruction);
static unsigned runGas(Instruction _instruction, langutil::EVMVersion _evmVersion);
/// @returns the gas cost of the supplied data, depending whether it is in creation code, or not.
/// In case of @a _inCreation, the data is only sent as a transaction and is not stored, whereas
@ -257,5 +257,4 @@ inline std::ostream& operator<<(std::ostream& _str, GasMeter::GasConsumption con
return _str << std::dec << _consumption.value;
}
}

29
libevmasm/Inliner.cpp
View File

@ -38,7 +38,6 @@
#include <optional>
#include <limits>
using namespace std;
using namespace solidity;
using namespace solidity::evmasm;
@ -54,7 +53,7 @@ u256 executionCost(RangeType const& _itemRange, langutil::EVMVersion _evmVersion
[&gasMeter](auto const& _item) { return gasMeter.estimateMax(_item, false); }
), GasMeter::GasConsumption());
if (gasConsumption.isInfinite)
return numeric_limits<u256>::max();
return std::numeric_limits<u256>::max();
else
return gasConsumption.value;
}
@ -66,14 +65,14 @@ uint64_t codeSize(RangeType const& _itemRange)
[](auto const& _item) { return _item.bytesRequired(2, Precision::Approximate); }
), 0u);
}
/// @returns the tag id, if @a _item is a PushTag or Tag into the current subassembly, nullopt otherwise.
optional<size_t> getLocalTag(AssemblyItem const& _item)
/// @returns the tag id, if @a _item is a PushTag or Tag into the current subassembly, std::nullopt otherwise.
std::optional<size_t> getLocalTag(AssemblyItem const& _item)
{
if (_item.type() != PushTag && _item.type() != Tag)
return nullopt;
return std::nullopt;
auto [subId, tag] = _item.splitForeignPushTag();
if (subId != numeric_limits<size_t>::max())
return nullopt;
if (subId != std::numeric_limits<size_t>::max())
return std::nullopt;
return tag;
}
}
@ -99,7 +98,7 @@ bool Inliner::isInlineCandidate(size_t _tag, ranges::span<AssemblyItem const> _i
return true;
}
map<size_t, Inliner::InlinableBlock> Inliner::determineInlinableBlocks(AssemblyItems const& _items) const
std::map<size_t, Inliner::InlinableBlock> Inliner::determineInlinableBlocks(AssemblyItems const& _items) const
{
std::map<size_t, ranges::span<AssemblyItem const>> inlinableBlockItems;
std::map<size_t, uint64_t> numPushTags;
@ -108,7 +107,7 @@ map<size_t, Inliner::InlinableBlock> Inliner::determineInlinableBlocks(AssemblyI
{
// The number of PushTags approximates the number of calls to a block.
if (item.type() == PushTag)
if (optional<size_t> tag = getLocalTag(item))
if (std::optional<size_t> tag = getLocalTag(item))
++numPushTags[*tag];
// We can only inline blocks with straight control flow that end in a jump.
@ -116,7 +115,7 @@ map<size_t, Inliner::InlinableBlock> Inliner::determineInlinableBlocks(AssemblyI
if (lastTag && SemanticInformation::breaksCSEAnalysisBlock(item, false))
{
ranges::span<AssemblyItem const> block = _items | ranges::views::slice(*lastTag + 1, index + 1);
if (optional<size_t> tag = getLocalTag(_items[*lastTag]))
if (std::optional<size_t> tag = getLocalTag(_items[*lastTag]))
if (isInlineCandidate(*tag, block))
inlinableBlockItems[*tag] = block;
lastTag.reset();
@ -130,7 +129,7 @@ map<size_t, Inliner::InlinableBlock> Inliner::determineInlinableBlocks(AssemblyI
}
// Store the number of PushTags alongside the assembly items and discard tags that are never pushed.
map<size_t, InlinableBlock> result;
std::map<size_t, InlinableBlock> result;
for (auto&& [tag, items]: inlinableBlockItems)
if (uint64_t const* numPushes = util::valueOrNullptr(numPushTags, tag))
result.emplace(tag, InlinableBlock{items, *numPushes});
@ -199,7 +198,7 @@ bool Inliner::shouldInlineFullFunctionBody(size_t _tag, ranges::span<AssemblyIte
return false;
}
optional<AssemblyItem> Inliner::shouldInline(size_t _tag, AssemblyItem const& _jump, InlinableBlock const& _block) const
std::optional<AssemblyItem> Inliner::shouldInline(size_t _tag, AssemblyItem const& _jump, InlinableBlock const& _block) const
{
assertThrow(_jump == Instruction::JUMP, OptimizerException, "");
AssemblyItem blockExit = _block.items.back();
@ -232,7 +231,7 @@ optional<AssemblyItem> Inliner::shouldInline(size_t _tag, AssemblyItem const& _j
return blockExit;
}
return nullopt;
return std::nullopt;
}
@ -252,7 +251,7 @@ void Inliner::optimise()
AssemblyItem const& nextItem = *next(it);
if (item.type() == PushTag && nextItem == Instruction::JUMP)
{
if (optional<size_t> tag = getLocalTag(item))
if (std::optional<size_t> tag = getLocalTag(item))
if (auto* inlinableBlock = util::valueOrNullptr(inlinableBlocks, *tag))
if (auto exitItem = shouldInline(*tag, nextItem, *inlinableBlock))
{
@ -264,7 +263,7 @@ void Inliner::optimise()
// We might increase the number of push tags to other blocks.
for (AssemblyItem const& inlinedItem: inlinableBlock->items)
if (inlinedItem.type() == PushTag)
if (optional<size_t> duplicatedTag = getLocalTag(inlinedItem))
if (std::optional<size_t> duplicatedTag = getLocalTag(inlinedItem))
if (auto* block = util::valueOrNullptr(inlinableBlocks, *duplicatedTag))
++block->pushTagCount;

15
libevmasm/Instruction.cpp
View File

@ -22,7 +22,6 @@
#include <libevmasm/Instruction.h>
using namespace std;
using namespace solidity;
using namespace solidity::util;
using namespace solidity::evmasm;
@ -76,7 +75,8 @@ std::map<std::string, Instruction> const solidity::evmasm::c_instructions =
{ "COINBASE", Instruction::COINBASE },
{ "TIMESTAMP", Instruction::TIMESTAMP },
{ "NUMBER", Instruction::NUMBER },
{ "DIFFICULTY", Instruction::DIFFICULTY },
{ "DIFFICULTY", Instruction::PREVRANDAO },
{ "PREVRANDAO", Instruction::PREVRANDAO },
{ "GASLIMIT", Instruction::GASLIMIT },
{ "CHAINID", Instruction::CHAINID },
{ "SELFBALANCE", Instruction::SELFBALANCE },
@ -93,6 +93,7 @@ std::map<std::string, Instruction> const solidity::evmasm::c_instructions =
{ "MSIZE", Instruction::MSIZE },
{ "GAS", Instruction::GAS },
{ "JUMPDEST", Instruction::JUMPDEST },
{ "PUSH0", Instruction::PUSH0 },
{ "PUSH1", Instruction::PUSH1 },
{ "PUSH2", Instruction::PUSH2 },
{ "PUSH3", Instruction::PUSH3 },
@ -174,6 +175,7 @@ std::map<std::string, Instruction> const solidity::evmasm::c_instructions =
{ "SELFDESTRUCT", Instruction::SELFDESTRUCT }
};
/// @note InstructionInfo is assumed to be the same across all EVM versions except for the instruction name.
static std::map<Instruction, InstructionInfo> const c_instructionInfo =
{ // Add, Args, Ret, SideEffects, GasPriceTier
{ Instruction::STOP, { "STOP", 0, 0, 0, true, Tier::Zero } },
@ -223,7 +225,7 @@ static std::map<Instruction, InstructionInfo> const c_instructionInfo =
{ Instruction::COINBASE, { "COINBASE", 0, 0, 1, false, Tier::Base } },
{ Instruction::TIMESTAMP, { "TIMESTAMP", 0, 0, 1, false, Tier::Base } },
{ Instruction::NUMBER, { "NUMBER", 0, 0, 1, false, Tier::Base } },
{ Instruction::DIFFICULTY, { "DIFFICULTY", 0, 0, 1, false, Tier::Base } },
{ Instruction::PREVRANDAO, { "PREVRANDAO", 0, 0, 1, false, Tier::Base } },
{ Instruction::GASLIMIT, { "GASLIMIT", 0, 0, 1, false, Tier::Base } },
{ Instruction::CHAINID, { "CHAINID", 0, 0, 1, false, Tier::Base } },
{ Instruction::SELFBALANCE, { "SELFBALANCE", 0, 0, 1, false, Tier::Low } },
@ -240,6 +242,7 @@ static std::map<Instruction, InstructionInfo> const c_instructionInfo =
{ Instruction::MSIZE, { "MSIZE", 0, 0, 1, false, Tier::Base } },
{ Instruction::GAS, { "GAS", 0, 0, 1, false, Tier::Base } },
{ Instruction::JUMPDEST, { "JUMPDEST", 0, 0, 0, true, Tier::Special } },
{ Instruction::PUSH0, { "PUSH0", 0, 0, 1, false, Tier::Base } },
{ Instruction::PUSH1, { "PUSH1", 1, 0, 1, false, Tier::VeryLow } },
{ Instruction::PUSH2, { "PUSH2", 2, 0, 1, false, Tier::VeryLow } },
{ Instruction::PUSH3, { "PUSH3", 3, 0, 1, false, Tier::VeryLow } },
@ -321,15 +324,17 @@ static std::map<Instruction, InstructionInfo> const c_instructionInfo =
{ Instruction::SELFDESTRUCT, { "SELFDESTRUCT", 0, 1, 0, true, Tier::Special } }
};
InstructionInfo solidity::evmasm::instructionInfo(Instruction _inst)
InstructionInfo solidity::evmasm::instructionInfo(Instruction _inst, langutil::EVMVersion _evmVersion)
{
try
{
if (_inst == Instruction::PREVRANDAO && _evmVersion < langutil::EVMVersion::paris())
return InstructionInfo({ "DIFFICULTY", 0, 0, 1, false, Tier::Base });
return c_instructionInfo.at(_inst);
}
catch (...)
{
return InstructionInfo({"<INVALID_INSTRUCTION: " + to_string(static_cast<unsigned>(_inst)) + ">", 0, 0, 0, false, Tier::Invalid});
return InstructionInfo({"<INVALID_INSTRUCTION: " + std::to_string(static_cast<unsigned>(_inst)) + ">", 0, 0, 0, false, Tier::Invalid});
}
}

Some files were not shown because too many files have changed in this diff Show More