Improve AVM doc generation for downstream tooling

[barnjamin]

Problem

The primary source of easily ingestible information for the details of AVM opcodes is the langspec.json file. This file is critical for higher level languages or tooling to easily update to new versions and perform better type checking.

Currently the langspec.json file contains a list of OpSpec details and some Fields that can be used as immediate arguments. There are a number of shortcomings of the current format if they're meant to be used by downstream tooling.

Shortcomings include:

• Lack of easily parsed immediate fields, argument name referenced in docs isn't available directly
• Difficult versioning representation (costs by version, fields available by version, first introduced)
• Lack of semantic information in an easily parsed format
  • We know txn Sender puts a 32 byte slice on the stack, we can call this address
  • We know an == op puts a 1/0 on the stack, we can call this boolean
  • We know the b+ op can take, maximally, a 64 byte string, we can call this bigint

Solution

1) Create a higher level type to replace the current StackType where we can define the bounds for the more specific type and provide a name to reference them in docs. Because this StackType is used in the opdoc tool, the smallest changes possible for that to work are also included in this change set.

2) Modify the existing Immediate documentation to provide the Name and FieldGroup if available and make the syntax and bytecode for each op more explicit.

WIP: https://github.com/algorand/go-algorand/pull/5130

3) Incorporate the changes in the above steps and produce a version of the langspec.json file for each version available with exactly (and only) the details available in that version. Improve TEAL_* docs to produce a symbolic stack that is easier to read (https://github.com/algorand/go-algorand/pull/5130/files#r1150703089)

4) Add directives to docs (pragma, define)

[algoanne]

what about including cost in the langspec? (follow-on issue)

[algoanne]

the high-level goal of this work is support things like tealish that need to know stuff about our opcodes. If we improve langspec.json to express more details, that will help.

[algoanne]

@barnjamin Should we review & merge the PR's in the order described? Is each PR mergeable on its own?

[barnjamin]

@algoanne

what about including cost in the langspec? (follow-on issue)

I didnt mention it but it should be part of one of the existing issues, and one of the big contributing factors to creating a langspec per version (to avoid wild schema to describe diff version costs or args)

Should we review & merge the PR's in the order described? Is each PR mergeable on its own?

The rest are dependent on the first, besides that I think the others can be considered separately though all going towards the same goal

[FrankSzendzielarz]

what about including cost in the langspec? (follow-on issue)

it used to be in there I think until dynamic opcode cost was introduced for some opcodes, eg: https://developer.algorand.org/docs/get-details/dapps/avm/teal/opcodes/#json_ref-r

[algoanne]

Remaining work:

All we need to do now is loop over TEAL versions 1-9 and generate the langspecs separately for each one. Should only need to do this once.

Have to handle costs which changed for different versions, so need to make sure that the right costs are published for each version. The prototypes (inputs) also changed slightly from version to version. e.g. app_local_get could take a slot or absolute. But hopefully this just falls out, so just confirm.

3 pts estimated.

[jannotti]

We forgot to note that we should ensure that fields only appear in the versions they are supported in. (It might fall out from the simple version loop, but I'm less sure of that than I was about cost)