Update documentation to describe `finalize` scope, program mappings, and public state
Closed this issue · 3 comments
Motivation
Currently, our documentation available at developer.aleo.org is lacking information on the finalize scope or any information about program mappings, generally. This makes it difficult for new developers to the Aleo ecosystem to understand the potentialities and constraints of writing code and deploying programs on Aleo. In addition, it makes it difficult for existing members of the Aleo community & developer relations engineers to explain the system. As we strive to make Leo the ZK language of choice, we need to ensure that all the features of the language are properly documented
Feature Description
New pages should be added to the developer documentation, explaining the finalize scope in the context of a broader transaction model as well as independently. A description of program mappings, who can access them, and how they are limited (e.g. in terms of size) should also exist. Finally, a detailed description of the cost (per opcode) for the finalize scope should be included as a reference.
End State
Aleo documentation is fully consistent with and properly communicates the reality as implemented in Leo and snarkVM. In addition, a full description of these features increases developer excitement and interest in Aleo. Finally, both Aleo team members and ambassadors have a resource from which they can answer questions to new community members/developers coming from within and without the blockchain ecosystem.
As an added note, we should also document the extensions we made to make this programming model more intuitive.
e.g async, futures, and awaits.
Happy to be a resource for questions around these topics.
I agree that more documentation on finalize would be useful. The question also came up in live workshops, e.g., why we use finalize in only some of our workshop examples, and in some of the examples and the deploy workshop we don’t use it. So we could either clarify it in the finalize documentation when finalize is useful and link the corresponding workshop examples, or also add some context to the workshop documentations
I agree that more documentation on finalize would be useful. The question also came up in live workshops, e.g., why we use finalize in only some of our workshop examples, and in some of the examples and the deploy workshop we don’t use it. So we could either clarify it in the finalize documentation when finalize is useful and link the corresponding workshop examples, or also add some context to the workshop documentations
Echoing the sentiment here. It's a common question during live workshops and from developers building things on the platform. I typically spend a few minutes during presentations specifically going over the difference between transition and finalize, their respective limitations and when you would use one or the other. It would be great if we had a place in the docs to point people for additional context