Complete Parser for Solidity with ANTLR4

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
3. Usage
4. Contributing
5. License
6. Contact

About The Project

The currently maintained Solidity parser by the Solidity team focuses on parsing the 'latest stable version' of Solidity. The latest stable version of Solidity is v0.8.11 at the moment of writing, but according to my investigations, more than 99% of Ethereum verified smart contracts are compiled with Solidity v0.6.0 and lower.

I needed a universal parser which would be compatible with all compiler versions (especially v0.6.0 and lower), so this project is all about building a complete Solidity parser able to parse all compiler versions of Solidity.

This work includes:

1. Solidity Language grammar in ANTLR4 .g4 format.

   The .g4 grammar is an extension of https://github.com/solidity-parser/antlr, where I have revised the grammar to accept code for all Solidity compiler versions up to v0.8.0.

2. visitor and listener implementation in Python3.

   I went through a lot of twists and turns writing these two because there weren't a lot of examples to refer to. I am opening my code hoping it would help people write their own visitor or listener implementations for their grammar written in ANTLR4.

Built With

• ANTLR4

• Python3

(back to top)

Getting Started

Following instructions are for those who would like to try out the visitor or the listener.

Prerequisites

Python 3

Python version 3.8.X (I have used 3.8.5) with antlr4-python3-runtime package installed.

$ pip install antlr4-python3-runtime

(Optional) ANTLR4

If you wish to edit the .g4 and try out your own grammar, set up ANTLR4 (I have used version 4.9.2).

• For Windows: Following blog gives good step-by-step instructions for Windows.

• For Mac:

  1. install ANTLR

  $ cd /usr/local/lib
  $ curl -O https://www.antlr.org/download/antlr-4.9.2-complete.jar

  2. add CLASSPATH in .bash_profile or an equivalent startup script (.zshrc)

  $ export CLASSPATH=".:/usr/local/lib/antlr-4.9.2-complete.jar:$CLASSPATH"

  3. create aliases

  $ alias antlr4='java -Xmx500M -cp "/usr/local/lib/antlr-4.9.2-complete.jar:$CLASSPATH" org.antlr.v4.Tool'
  $ alias grun='java -Xmx500M -cp "/usr/local/lib/antlr-4.9.2-complete.jar:$CLASSPATH" org.antlr.v4.gui.TestRig'

(back to top)

Usage

How to try out the visitor or the listener

I have written a sample code using the visitor and the listener in run_parser.py. Detailed explanation is provided through comments in the code.

Try them out and play with them by adding code lines in the main function!

(Optional) To regenerate lexer and parser

If you have edited the .g4 file, you will have to regenerate its lexer and parser using the below command.

$ antlr4 -o /antlr4-generated/ -Dlanguage=Python3 -visitor Solidity.g4

For more information on the usage options, refer to ANTLR Tool Command Line Options

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

1. Fork the Project

2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

3. Commit your Changes (git commit -m 'Add some AmazingFeature')

4. Push to the Branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

(back to top)

License

Distributed under the GNU General Public License v3.0. See LICENSE for more information.

(back to top)

Contact

Yejin Kelly Joo - [email protected]

Project Link: github repo

(back to top)