Pyteal 0.24.0: Sourcemapping!

The new pyteal release (0.24.0) introduces sourcemapping. This feature will help the savvy developer debug and optimize her pyteal program.

Running a pyteal program produces TEAL, which is then compiled to the bytecode that is deployed and run on the Algorand blockchain. TEAL is a stack-based language, less accessible for development than pyteal. However, TEAL is what is actually run by the blockchain. For this reason, TEAL is what is typically audited.

Pyteal sourcemapping bridges the gap between pyteal and TEAL. Here is an example output from the sourcemapper:

On the top left is the pyteal program. On the right is the annotated teal. The annotated TEAL is the same TEAL as would normally be output from the pyteal, but with additional comments. These comments include the pyteal line that produced the TEAL, as well as the pyteal line number.

Note that a PC-to-TEAL line map already exists. With the new pyteal-to-TEAL map, we can now compose the two maps to get a pyteal-to-PC map. Now when you get an error, like in the example above, “assert failed pc=70”, you know exactly which pyteal line the program errored on.

Due to the nature of the pyteal to TEAL relationship, certain lines of pyteal will produce many lines of TEAL. It will also sometimes be the case that several lines of pyteal together produce a chunk of TEAL. The sourcemapper is not intended to provide complete and perfect information in every situation, but rather to guide debugging efforts. There are known edge cases (not common) where the sourcemapper will not be able to provide the pyteal line.

Ready to use it? Here is a walkthrough of how to enable the sourcemapper for your pyteal: https://github.com/algorand/pyteal/blob/master/docs/sourcemap.rst

One minor caveat to be aware of: turning on the sourcemapper will affect compilation time. On a large program, it might take a few minutes to complete.