Solidity binary address to source code mapper

The mapper accepts the solidity compiler output in standard JSON format and a hexadecimal address (program counter) of the deployed (runtime) bytecode as inputs. It then returns the file name, line number, and a segment of the line corresponding to the provided hexadecimal address.

Requirements

• Python 3
• ijson 3.3.0 (used to parse large json files)

Installation:

Install the libraries used by the Mapper

pip install -r requirements.txt

Getting Started

You can use the mapper in your python script using Mapper.map_hex_address(...) as follows:

Mapper.map_hex_address(
    compiler_output_json="../BeerBar.json",
    address_hex="0x1525",
    contract_name="BeerBar",
)

Or you can run it from the command line like this:

python mapper.py --compiler_output_json ../BeerBar.json --address_hex 0x1525 --contract_name BeerBar

Parameter	Explanation
compiler_output_json	Json generated by the Solidity compiler in standard json format. It must contain the output sections "srcmap" (evm.deployedBytecode.sourceMap), "object" (evm.deployedBytecode.object) and metadata. In addition, "metadata" must contain the source content. To do this, you have to set useLiteralContent in metadata to true. For further information see the provided example compiler_config in the end of the README.
address_hex	Hexadecimal address or program counter in hex of the deployed runtime bytecode
contract_name	Name of the contract

The result is of class MapperResult containing line, code and file. Example: MapperResult(file="contract.sol", code="uint256 c = a * b", line=17). In the event of an error, the file path will be set to the contract name, the code snippet signifies the error message and the line number will be designated as 0.

Example compiler-config

The following example shows the minimal compiler_config.json to generate the required sections. You can find more example compiler configurations for different compiler versions in the tests folder.

{
  "language": "Solidity",
  "settings": {
    "metadata": {
      "useLiteralContent": true
    },
    "outputSelection": {
      "*": {
        "*": [
          "evm.deployedBytecode.sourceMap",
          "evm.deployedBytecode.object",
          "metadata"
        ]
      }
    }
  },
  "sources": {
    "ArtithmeticTestContract.sol": {
      "content": "pragma solidity ^0.8.0;\r\ncontract ArtithmeticTestContract {\r\n    function arithmeticOps(uint256 a, uint256 b) public pure returns (uint256, uint256, uint256, uint256) {\r\n        uint256 add = a + b;\r\n        uint256 sub = a - b;\r\n        uint256 mul = a * b;\r\n        uint256 div = b != 0 ? a / b : 0;\r\n        return (add, sub, mul, div);\r\n    }\r\n}"
    }
  }
}

Project structure

Path	Explanation
/	Readme, pyproject.toml (pytest config file)
/src/solidity_address_mapper	Source code
/tests	All files related to testing
/workdir	Collection of contracts and config files I keep for historical reasons