algorand / algorand/go-algorand

Improve AVM doc generation for downstream tooling

Aperta
#5,131 7 commenti 0 reazioni 1 assegnatario Assegnata a @jasonpaulos Vedi su GitHub
new-feature-request Team Scytale
Lingua principale
Go
Stelle
1.4k
Fork
537
Merge medio
1g 7h
PR unite (30g)
18

Descrizione

## Problem

The primary source of easily ingestible information for the details of AVM opcodes is the [langspec.json](https://github.com/algorand/go-algorand/blob/master/data/transactions/logic/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](https://github.com/algorand/go-algorand/blob/master/cmd/opdoc/opdoc.go), 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)

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.