Solidity Documentation Release 0.8.8 Ethereum Sep 24, 2021 BASICS 1 Getting Started 3 2 Translations 5 3 Contents 7 3.1 Introduction to Smart Contracts.....................................7 3.2 Installing the Solidity Compiler..................................... 15 3.3 Solidity by Example........................................... 23 3.4 Layout of a Solidity Source File..................................... 45 3.5 Structure of a Contract.......................................... 48 3.6 Types................................................... 51 3.7 Units and Globally Available Variables................................. 84 3.8 Expressions and Control Structures................................... 90 3.9 Contracts................................................. 103 3.10 Inline Assembly............................................. 141 3.11 Cheatsheet................................................ 145 3.12 Using the Compiler............................................ 149 3.13 Analysing the Compiler Output..................................... 165 3.14 Layout of State Variables in Storage................................... 168 3.15 Layout in Memory............................................ 175 3.16 Layout of Call Data........................................... 176 3.17 Cleaning Up Variables.......................................... 176 3.18 Source Mappings............................................. 177 3.19 The Optimizer.............................................. 178 3.20 Contract Metadata............................................ 197 3.21 Contract ABI Specification........................................ 200 3.22 Solidity v0.5.0 Breaking Changes.................................... 215 3.23 Solidity v0.6.0 Breaking Changes.................................... 223 3.24 Solidity v0.7.0 Breaking Changes.................................... 226 3.25 Solidity v0.8.0 Breaking Changes.................................... 228 3.26 NatSpec Format............................................. 231 3.27 Security Considerations......................................... 235 3.28 SMTChecker and Formal Verification.................................. 242 3.29 Resources................................................. 255 3.30 Import Path Resolution.......................................... 257 3.31 Yul.................................................... 266 3.32 Style Guide................................................ 288 3.33 Common Patterns............................................ 309 3.34 List of Known Bugs........................................... 315 3.35 Contributing............................................... 330 i 3.36 Solidity Brand Guide........................................... 338 3.37 Language Influences........................................... 339 Index 341 ii Solidity Documentation, Release 0.8.8 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 a curly-bracket language. It is influenced by C++, Python and JavaScript, and is designed to target the Ethereum Virtual Machine (EVM). You can find more details about which languages Solidity has been inspired byin the language influences section. 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. When deploying contracts, you should use the latest released version of Solidity. This is because breaking changes as well as new features and bug fixes are introduced regularly. We currently use a 0.x version number to indicate this fast pace of change. Warning: Solidity recently released the 0.8.x version that introduced a lot of breaking changes. Make sure you read the full list. Ideas for improving Solidity or this documentation are always welcome, read our contributors guide for more details. BASICS 1 Solidity Documentation, Release 0.8.8 2 BASICS CHAPTER ONE 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: • A simple example smart contract written in Solidity. • Blockchain Basics. • The Ethereum Virtual Machine. 2. Get to Know Solidity Once you are accustomed to the basics, we recommend you read the “Solidity by Example” and “Language Description” sections to understand the core concepts of the language. 3. Install the Solidity Compiler There are various ways to install the Solidity compiler, simply choose your preferred option and follow the steps outlined on the installation page. Hint: You can try out code examples directly in your browser with the Remix IDE. 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 con- tracts have their own unique issues to watch out for, so before working on production code, make sure you read the Security Considerations section. 4. Learn More If you want to learn more about building decentralized applications on Ethereum, the Ethereum Developer Resources can help you with further general documentation around Ethereum, and a wide selection of tutorials, tools and devel- opment frameworks. If you have any questions, you can try searching for answers or asking on the Ethereum StackExchange, or our Gitter channel. 3 Solidity Documentation, Release 0.8.8 4 Chapter 1. Getting Started CHAPTER TWO TRANSLATIONS Community volunteers help translate this documentation into several languages. They have varying degrees of com- pleteness and up-to-dateness. The English version stands as a reference. Note: We recently set up a new GitHub organization and translation workflow to help streamline the community efforts. Please refer to the translation guide for information on how to contribute to the community translations moving forward. • French (in progress) • Italian (in progress) • Japanese • Korean (in progress) • Russian (rather outdated) • Simplified Chinese (in progress) • Spanish • Turkish (partial) 5 Solidity Documentation, Release 0.8.8 6 Chapter 2. Translations CHAPTER THREE CONTENTS Keyword Index, Search Page 3.1 Introduction to Smart Contracts 3.1.1 A Simple Smart Contract Let us begin with a basic example that sets the value of a variable and exposes it for other contracts to access. It is fine if you do not understand everything right now, we will go into more detail later. Storage Example // SPDX-License-Identifier: GPL-3.0 pragma solidity >=0.4.16 <0.9.0; contract SimpleStorage { uint storedData; function set(uint x) public { storedData= x; } function get() public view returns (uint){ return storedData; } } The first line tells you that the source code is licensed under the GPL version 3.0. Machine-readable license specifiers are important in a setting where publishing the source code is the default. The next line specifies that the source code is written for Solidity version 0.4.16, or a newer version of the languageup to, but not including version 0.9.0. This is to ensure that the contract is not compilable with a new (breaking) compiler version, where it could behave differently. Pragmas are common instructions for compilers about how to treat the source code (e.g. pragma once). A contract in the sense of Solidity is a collection of code (its functions) and data (its state) that resides at a specific address on the Ethereum blockchain. The line uint storedData; declares a state variable called storedData of type uint (unsigned integer of 256 bits). You can think of it as a single slot in a database that you can query and alter by calling functions of the code that manages the database. In this example, the contract defines the functions set and get that can be used to modify or retrieve the value of the variable. 7 Solidity Documentation, Release 0.8.8 To access a member (like a state variable) of the current contract, you do not typically add the this. prefix, you just access it directly via its name. Unlike in some other languages, omitting it is not just a matter of style, it results in a completely different way to access the member, but more on this later. This contract does not do much yet apart from (due to the infrastructure built by Ethereum) allowing anyone to store a single number that is accessible by anyone in the world without a (feasible) way to prevent you from publishing this number. Anyone could call set again with a different value and overwrite your number, but the number is still stored in the history of the blockchain. Later, you will see how you can impose access restrictions so that only you can alter the number. Warning: Be careful with using Unicode text, as similar looking (or even identical) characters can have different code points and as such are encoded as a different byte array. Note: All identifiers (contract names, function names and variable names) are restricted to the ASCII character set.It is possible to store UTF-8 encoded data in string variables. Subcurrency Example The following contract