-repo.key by PAJO2018 · Pull Request #2030 · npm/documentation

PAJO2018 · 2026-08-29T23:59:30Z

"
{skip to content}

latest

English

BASICS

Introduction to Smart Contracts
Solidity by Example
Installing the Solidity Compiler
LANGUAGE DESCRIPTION

Layout of a Solidity Source File
Structure of a Contract
Types
Units and Globally Available Variables
Expressions and Control Structures
Contracts
Inline Assembly
Cheatsheet
Language Grammar
COMPILER

Using the Compiler
Using the Commandline Compiler
Setting the EVM Version to Target
Compiler Input and Output JSON Description
Input Description
Output Description
Experimental Mode
Analysing the Compiler Output
Solidity IR-based Codegen Changes
INTERNALS

Layout of State Variables in Storage and Transient Storage
Layout in Memory
Layout of Call Data
Cleaning Up Variables
Source Mappings
The Optimizer
Contract Metadata
Contract ABI Specification
ADVISORY CONTENT

Security Considerations
List of Known Bugs
Solidity v0.5.0 Breaking Changes
Solidity v0.6.0 Breaking Changes
Solidity v0.7.0 Breaking Changes
Solidity v0.8.0 Breaking Changes
ADDITIONAL MATERIAL

NatSpec Format
SMTChecker and Formal Verification
Yul
Import Path Resolution
RESOURCES

Style Guide
Common Patterns
Resources
Contributing
Language Influences
Solidity Brand Guide
Keyword Index
Using the Compiler
Using the Compiler
Using the Commandline Compiler
Note

This section does not apply to solcjs, not even if it is used in commandline mode.

Basic Usage
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.

Optimizer Options
Before you deploy your contract, activate the optimizer when compiling using solc --optimize --bin sourceFile.sol. By default, the optimizer will optimize the contract assuming it is called 200 times across its lifetime (more specifically, it assumes each opcode is executed around 200 times). If you want the initial contract deployment to be cheaper and the later function executions to be more expensive, set it to --optimize-runs=1. If you expect many transactions and do not care for higher deployment cost and output size, set --optimize-runs to a high number. This parameter has effects on the following (this might change in the future):

the size of the binary search in the function dispatch routine

the way constants like large numbers or strings are stored

Base Path and Import Remapping
The commandline compiler will automatically read imported files from the filesystem, but it is also possible to provide path redirects using prefix=path in the following way:

solc github.com/ethereum/dapp-bin/=/usr/local/lib/dapp-bin/ file.sol
This essentially instructs the compiler to search for anything starting with github.com/ethereum/dapp-bin/ under /usr/local/lib/dapp-bin.

When accessing the filesystem to search for imports, paths that do not start with ./ or ../ are treated as relative to the directories specified using --base-path and --include-path options (or the current working directory if base path is not specified). Furthermore, the part of the path added via these options will not appear in the contract metadata.

For security reasons the compiler has restrictions on what directories it can access. 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 --allow-paths /sample/path,/another/sample/path switch. Everything inside the path specified via --base-path is always allowed.

The above is only a simplification of how the compiler handles import paths. For a detailed explanation with examples and discussion of corner cases please refer to the section on path resolution.

Library Linking
If your contracts use libraries, you will notice that the bytecode contains substrings of the form $53aea86b7d70b31448b230b20ae141a537$ (format was different <v0.5.0). These are placeholders for the actual library addresses. The placeholder is a 34 character prefix of the hex encoding of the keccak256 hash of the fully qualified library name. The bytecode file will also contain lines of the form // -> at the end to help identify which libraries the placeholders represent. Note that the fully qualified library name is the path of its source file and the library name separated by :. You can use solc as a linker meaning that it will insert the library addresses for you at those points:

Either add --libraries "file.sol:Math=0x1234567890123456789012345678901234567890 file.sol:Heap=0xabCD567890123456789012345678901234567890" to your command to provide an address for each library (use commas or spaces as separators) or store the string in a file (one library per line) and run solc using --libraries fileName.

Note

Starting Solidity 0.8.1 accepts = as separator between library and address, and : as a separator is deprecated. It will be removed in the future. Currently --libraries "file.sol:Math:0x1234567890123456789012345678901234567890 file.sol:Heap:0xabCD567890123456789012345678901234567890" will work too.

If solc is called with the option --standard-json, it will expect a JSON input (as explained below) on the standard input, and return a JSON output on the standard output. This is the recommended interface for more complex and especially automated uses. The process will always terminate in a “success” state and report any errors via the JSON output. The option --base-path is also processed in standard-json mode.

If solc is called with the option --link, all input files are interpreted to be unlinked binaries (hex-encoded) in the $53aea86b7d70b31448b230b20ae141a537$-format given above and are linked in-place (if the input is read from stdin, it is written to stdout). All options except --libraries are ignored (including -o) in this case.

Warning

Manually linking libraries on the generated bytecode is discouraged because it does not update contract metadata. Since metadata contains a list of libraries specified at the time of compilation and bytecode contains a metadata hash, you will get different binaries, depending on when linking is performed.

You should ask the compiler to link the libraries at the time a contract is compiled by either using the --libraries option of solc or the libraries key if you use the standard-JSON interface to the compiler.

Note

The library placeholder used to be the fully qualified name of the library itself instead of the hash of it. This format is still supported by solc --link but the compiler will no longer output it. This change was made to reduce the likelihood of a collision between libraries, since only the first 36 characters of the fully qualified library name could be used.

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 behaviors.

Warning

Compiling for the wrong EVM version can result in wrong, strange and failing 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:

solc --evm-version contract.sol
In the standard JSON interface, use the "evmVersion" key in the "settings" field:

{
"sources": {/* ... /},
"settings": {
"optimizer": {/ ... */},
"evmVersion": ""
}
}
Target Options
Below is a list of target EVM versions and the compiler-relevant changes introduced at each version. Backward compatibility is not guaranteed between each version.

homestead (support deprecated)
(oldest version)

tangerineWhistle (support deprecated)
Gas cost for access to other accounts increased, relevant for gas estimation and the optimizer.

All gas sent by default for external calls, previously a certain amount had to be retained.

spuriousDragon (support deprecated)
Gas cost for the exp opcode increased, relevant for gas estimation and the optimizer.

byzantium (support deprecated)
Opcodes returndatacopy, returndatasize and staticcall are available in assembly.

The staticcall opcode is used when calling non-library view or pure functions, which prevents the functions from modifying state at the EVM level, i.e., even applies when you use invalid type conversions.

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.

Shifting operators use shifting opcodes and thus need less gas.

petersburg
The compiler behaves the same way as with constantinople.

istanbul
Opcodes chainid and selfbalance are available in assembly.

berlin
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
The block’s base fee (EIP-3198 and EIP-1559) can be accessed via the global block.basefee or basefee() in inline assembly.

paris
Introduces prevrandao() and block.prevrandao, and changes the semantics of the now deprecated block.difficulty, disallowing difficulty() in inline assembly (see EIP-4399).

shanghai
Smaller code size and gas savings due to the introduction of push0 (see EIP-3855).

cancun
The block’s blob base fee (EIP-7516 and EIP-4844) can be accessed via the global block.blobbasefee or blobbasefee() in inline assembly.

Introduces blobhash() in inline assembly and a corresponding global function to retrieve versioned hashes of blobs associated with the transaction (see EIP-4844).

Opcode mcopy is available in assembly (see EIP-5656).

Opcodes tstore and tload are available in assembly (see EIP-1153).

prague

osaka (default)
clz builtin function is available in inline assembly. (EIP-7939)

amsterdam (experimental)
The beacon chain slot number (EIP-7843) can be accessed via the global block.slotnum or slotnum() in inline assembly.

Compiler Input and Output JSON Description
The recommended way to interface with the Solidity compiler especially for more complex and automated setups is the so-called JSON-input-output interface. The same interface is provided by all distributions of the compiler.

The fields are generally subject to change, some are optional (as noted), but we try to only make backwards compatible changes.

The compiler API expects a JSON formatted input and outputs the compilation result in a JSON formatted output. The standard error output is not used and the process will always terminate in a “success” state, even if there were errors. Errors are always reported as part of the JSON output.

The following subsections describe the format through an example. Comments are of course not permitted and used here only for explanatory purposes.

Input Description
{
// Required: Source code language. Currently supported are "Solidity", "Yul", "SolidityAST" (experimental), "EVMAssembly" (experimental).
"language": "Solidity",
// Required
"sources":
{
// The keys here are the "global" names of the source files,
// imports can use other files via remappings (see below).
"myFile.sol":
{
// Optional: keccak256 hash of the source file
// It is used to verify the retrieved content if imported via URLs.
"keccak256": "0x123...",
// Required (unless "content" is used, see below): URL(s) to the source file.
// URL(s) should be imported in this order and the result checked against the
// keccak256 hash (if available). If the hash doesn't match or none of the
// URL(s) result in success, an error should be raised.
// Using the commandline interface only filesystem paths are supported.
// With the JavaScript interface the URL will be passed to the user-supplied
// read callback, so any URL supported by the callback can be used.
"urls":
[
"bzzr://56ab...",
"ipfs://Qma...",
"/tmp/path/to/file.sol"
// If files are used, their directories should be added to the command-line via
// --allow-paths <path>.
]
},
"settable":
{
// Optional: keccak256 hash of the source file
"keccak256": "0x234...",
// Required (unless "urls" is used): literal contents of the source file
"content": "contract settable is owned { uint256 private x = 0; function set(uint256 _x) public { if (msg.sender == owner) x = _x; } }"
},
"myFile.sol_json.ast":
{
// If language is set to "SolidityAST", an AST needs to be supplied under the "ast" key
// and there can be only one source file present.
// The format is the same as used by the ast output.
// 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": { ... }
},
"myFile_evm.json":
{
// If language is set to "EVMAssembly", an EVM Assembly JSON object needs to be supplied
// under the "assemblyJson" key and there can be only one source file present.
// The format is the same as used by the evm.legacyAssembly output or --asm-json
// output on the command line.
// Note that importing EVM assembly is experimental.
"assemblyJson":
{
".code": [ ... ],
".data": { ... }, // optional
"sourceList": [ ... ] // optional (if no source node was defined in any .code object)
}
}
},
// Optional
"settings":
{
// Optional: Stop compilation after the given stage. Currently only "parsing" is valid here
"stopAfter": "parsing",
// Optional: List of remappings
"remappings": [ ":g=/dir" ],
// Optional: Experimental mode toggle (Default: false)
// Makes it possible to use experimental features (but does not enable any such feature by itself).
// The use of this mode is recorded in contract metadata.
"experimental": true,
// Optional: Optimizer settings
"optimizer": {
// Turn on the optimizer. Optional. Default: false.
// NOTE: The state of the optimizer is fully determined by the 'details' dict and this setting
// only affects its defaults - when enabled, all components default to being enabled.
// The opposite is not true - there are several components that always default to being
// enabled an can only be explicitly disabled via 'details'.
// WARNING: Before version 0.8.6 omitting this setting was not equivalent to setting
// it to false and would result in all components being disabled instead.
// WARNING: Enabling optimizations for EVMAssembly input is allowed but not necessary under normal
// circumstances. It forces the opcode-based optimizer to run again and can produce bytecode that
// is not reproducible from metadata.
"enabled": true,
// Optimize for how many times you intend to run the code. Optional. Default: 200.
// Lower values will optimize more for initial deployment cost, higher
// values will optimize more for high-frequency usage.
"runs": 200,
// State of all optimizer components. Optional.
// Default values are determined by whether the optimizer is enabled or not.
// Note that the 'enabled' setting only affects the defaults here and has no effect when
// all values are provided explicitly.
"details": {
// Peephole optimizer (opcode-based). Optional. Default: true.
// Default for EVMAssembly input: false when optimization is not enabled.
// NOTE: Always runs (even with optimization disabled) except for EVMAssembly input or when explicitly turned off here.
"peephole": true,
// Inliner (opcode-based). Optional. Default: true when optimization is enabled.
"inliner": false,
// Unused JUMPDEST remover (opcode-based). Optional. Default: true.
// Default for EVMAssembly input: false when optimization is not enabled.
// NOTE: Always runs (even with optimization disabled) except for EVMAssembly input or when explicitly turned off here.
"jumpdestRemover": true,
// Literal reordering (codegen-based). Optional. Default: true when optimization is enabled.
// Moves literals to the right of commutative binary operators during code generation, helping exploit associativity.
"orderLiterals": false,
// Block deduplicator (opcode-based). Optional. Default: true when optimization is enabled.
// Unifies assembly code blocks that share content.
"deduplicate": false,
// Common subexpression elimination (opcode-based). Optional. Default: true when optimization is enabled.
// This is the most complicated step but can also provide the largest gain.
"cse": false,
// Constant optimizer (opcode-based). Optional. Default: true when optimization is enabled.
// Tries to find better representations of literal numbers and strings, that satisfy the
// size/cost trade-off determined by the 'runs' setting.
"constantOptimizer": false,
// Unchecked loop increment (codegen-based). Optional. Default: true.
// Use unchecked arithmetic when incrementing the counter of 'for' loops under certain circumstances.
// NOTE: Always runs (even with optimization disabled) unless explicitly turned off here.
"simpleCounterForLoopUncheckedIncrement": true,
// Yul optimizer. Optional. Default: true when optimization is enabled.
// Used to optimize the IR produced by the Yul IR-based pipeline as well as inline assembly
// and utility Yul code generated by the compiler.
// NOTE: Before Solidity 0.6.0 the default was false.
"yul": false,
// Tuning options for the Yul optimizer. Optional.
"yulDetails": {
// Improve allocation of stack slots for variables, can free up stack slots early.
// Optional. Default: true if Yul optimizer is enabled.
"stackAllocation": true,
// Optimization step sequence.
// The general form of the value is "

:".
// The setting is optional and when omitted, default values are used for both sequences.
// If the value does not contain the ':' delimiter, it is interpreted as the main
// sequence and the default is used for the cleanup sequence.
// To make one of the sequences empty, the delimiter must be present at the first or last position.
// In particular if the whole value consists only of the delimiter, both sequences are empty.
// Note that there are several hard-coded steps that always run, even when both sequences are empty.
// For more information see "The Optimizer > Selecting Optimizations".
"optimizerSteps": "dfDvulfnTUtnIf..."
}
}
},
// Version of the EVM to compile for (optional).
// Affects type checking and code generation. Can be homestead,
// tangerineWhi"
{skip to content}