ARC56: Extended App Description

[joe-p]

Basically takes most of the ideas in ARC32 and reorgs it in a way that is backwards compatible with ARC4 clients. Main benefit of this is HLLs can simply generate one JSON artifact.

[robdmoore]

I know the eventual goal is to use simulate, but I wonder if we add in optional per-method hints for things like:

• Fees
• Boxes
• Foreign arrays (? where you don't want that in the method selector)

And also:

• Template variables?

Are there other things that have come up in the past worth considering while we are looking at this?

[joe-p]

I know the eventual goal is to use simulate, but I wonder if we add in optional per-method hints for things like:

Fees
Boxes
Foreign arrays (? where you don't want that in the method selector)

My rationale for not including a field for these sort of things is that they can be dynamic which can be hard to describe in JSON and they could be network dependent. It also is not easy for a HLL to autogenerate these sorts of things and if the dev is required to manually write them out might as well just have them write a standardized readonly method that returns this information so they have the full power of the language and contract state/methods at their disposal (see ARC51).

Template variables?

Yes good call.

[joe-p]

Nice thing is that also gives future extensibility for other pcOffset values in the future?

This is why I think just having a completely seperate key in each SourceInfo is nice. Clients can look for pc or cblocksPcOffset. In the future we can just use a different key name for different methods if we want to implement them. Clients that don't support this new method will simply not resolve errors, but nothing will crash and burn.

[joe-p]

I do like putting pcOffset at the top level though so it's easy to discover which method is being used

[robdmoore]

Exactly, the thing is the same treatment will apply to all items so it makes more sense to have a key at the top level than change the key at the lower levels.

Then, for optimisation purposes it should be possible (default even?) to indicate there is no offset and they are absolute vs it's a cBlock offset.

The worst case of a client not supporting the offset type isn't a huge deal it just means the debugging info will be off, but if the mechanism to specify the type of offset exists on day 1 clients can read that value and act base don it (including opting out of debugging if it's a value they don't understand). I think that's way cleaner and less confusing than needing to read individual items and look for different keys. It's more efficient and more explicit.

On reflection, we also probably don't need the teal line offset since we can calculate that from source map if we have it and if we don't have it we can calculate it from the program bytes!

[robdmoore]

i.e.

sourceInfo: {
  approval: {
    pcOffset: 'cBlock' | 'none',
    mappings: [{pc: 4, ...}, ...]
  }
}

[daniel-makerx]

On reflection, we also probably don't need the teal line offset since we can calculate that from source map if we have it and if we don't have it we can calculate it from the program bytes!

Unfortunately source map on it's own isn't enough to know which line has the constant blocks as it only has line -> pc mappings

So if we are going to have the tealOffset option then that would need to be in the spec. But if we are going to support parsing bytecode anyway for the cBlock option maybe that is enough for now? It is explicit which is the key thing I wanted to see in the spec.

[robdmoore]

Ahh yeah that was my mistake.

I think it would be good to have an optional tealOffset key if the pcOffset is cBlock to avoid the extra byte code lookup, but it's not a hill I'd die on so comfortable if we don't have it.

[cusma]

@robdmoore @joe-p here you can find the ARC about AVM run time error in program bytecode I was mentioning in previous comments: #315 (cc: @nullun)

[joe-p]

@daniel-makerx @robdmoore In 35a19b3 I added ProgramSourceInfo interface that includes a pcOffsetMethod key.

I think it would be good to have an optional tealOffset key if the pcOffset is cBlock to avoid the extra byte code lookup, but it's not a hill I'd die on so comfortable if we don't have it.

Depending on consistency in decompiled output makes me a bit nervous. I think it's unlikely to change but I also think it's relatively easy to parse the cblocks if they are at the top of the program.

[daniel-makerx]

I assume name is meant to be a variable name?

Wondering if this should be an array with an optional name (and maybe description?) as scratch slots might be used without an associated name? Or perhaps the key should be the slot number since that is required and unique?

Additionally I also assume this is just for documenting scratch variables intended to be read by other applications, not necessarily every scratch slot used?

[joe-p]

Additionally I also assume this is just for documenting scratch variables intended to be read by other applications, not necessarily every scratch slot used?

Yeah exactly. The main purpose of having this field is so other contracts can easily access scratch variables. For example, TEALScript compiler uses scratch but this is only populated by user-defined scratch slots. I think forcing a name to be defined is fine because that's how it would be defined in the HLL. You can't have a property that is just a number so a name needs to be defined. I definitely like adding a desc though

[daniel-makerx]

Minor thing, noticed both StructField and this mapping don't have any sort of desc property, might be useful to have?

[joe-p]

In 19c6269 I removed teal from SourceInfo because we agreed it was only useful for developers reading the file. I realized, however, that the TEAL line numbers are also used to give better error messages even without an explicit error message, so I've added it back as an optional field RECOMMENDED for development, along with a source string

[neilcampbell]

Suggested change

	* included, but the corresponding genesis hash key MUST also be define
	* included, but the corresponding genesis hash key MUST also be defined

[neilcampbell]

Suggested change

	/** Named structs use by the application. Each struct field appears in the same order as ABI encoding. */
	/** Named structs used by the application. Each struct field appears in the same order as ABI encoding. */

[neilcampbell]

Suggested change

	/** A mapping of template variable names as they appear in the teal (not including TMPL_ prefix) to their respective types and values (if applicable) */
	/** A mapping of template variable names as they appear in the TEAL (not including TMPL_ prefix) to their respective types and values (if applicable) */

[neilcampbell]

Suggested change

	/** If given, the the base64 encoded value used for the given app/program */
	/** If given, the base64 encoded value used for the given app/program */