Solidity Source Mappings

Solidity Source Mappings Main Tips

  • The Solidity source mappings are static analysis tools operating on bytecode level, used to keep track of the where the source code is inside the debugger.
  • Source mappings utilize integer identifiers to refer to source files.

Solidity Source Mappings

Being a part of the AST output, the compiler would provide the source code range represented by the corresponding node insiode the AST.

The advantage of this is that it can be utlized for all kinds of purposes that range from tools of static analysis which would report errors according to the AST, as well as debugging tools which can highlight local variables with their respective uses.

Moreover, the compiler is also capable of generating a mapping from the bytecode into the source code’s range, which generated the instruction itself. Once again, this is important for tools of static analysis, which operate on bytecode level in addition to being used to display the present position inside the source code in the debugger or to handle breakpoints.

Either kind of source mappings uses integer indentifiers for referring to source files. Those are normal array indices inside a source file list, usually referred to as “sourceList”, which is a portion of the combined-json and the json / npm compiler output.

This the notation that source mappings use in the AST:


s in this context would be the byte-offset to the beginning of the source file’s range.

l would then be the length of the source range measured in bytes.

f would be the source index that we mention above.

The source mapping encoding for the bytecode gets more complex: It is a list that consists of s:l:f:j separated by semicolons ;. Every one of those elements corresponds to a certain instruction, for example you are not allowed to use the byte offset, however, must use the instruction offset. Keep in mind that push instructions tend to be longer than a single byte.

The fields named sl and f correspond to the ones described above.

j may be io or _ which signifies if a jump instruction goes to, returns from a function, or is a normal jump as an element of, say, a loop.

If you would like to compress those source mappings, notably for bytecode, you have to refer to these two rules:

  • For empty fields, the preceding element’s value is used.
  • In case a : symbol is omitted, all of the fields after that are considered as empty.

What this mean is that both of these source mappings are representing identical information:

Read previous post:
Solidity Internals Optimizer

Solidity Internals Optimizer Main Tips Because of Solidity optimizer operating on assembly, it is usable with other languages than Solidity. The Solidity...