feat: initial learn section

[heueristik]

This is a work by @heindel that I split into separate branches

[heueristik]

First round of review for @heindel

[heueristik]

The causality is wrong here.
Applications don't make the intent-machine run.
Applications can be run on intent-machines.

[heindel]

The intended meaning was that end-users use applications and applications run on Anoma as OS.

This needs to be changed in any case. Possibly, we may even get rid of the intent-machine and only talk about Anoma as OS.

[heueristik]

I am confused.

Applications are constituted by state, which is modelled as resources, and logic which can be divided into

• resource logic functions
• transaction functions
• projection functions

The latter two constitute the interface of an application and the prior the backend.

Resource kinds alone don't make up an application, and solvers are optional for applications.

What you write here deviates a lot from https://github.com/anoma/ART-2024-Heuer-Reusche-Cubides-Resource-Machine-Applications and I wonder why

[heueristik]

What does "fabricating" mean here?

Transaction objects can be balanced or unbalanced. A solver combines unbalanced transaction objects into balanced ones.

fabricating transaction objects from user intents

This sounds a bit misleading.
Practically, an intent is an unbalanced transaction object containing an ephemeral resource being part of a transaction that expresses constraints over it.
So intents are transaction themselves. This sentence sounds like and transaction is created from an intent.
However, transactions expressing intents are matched and combined with each other.

[heindel]

Thanks a lot for revising the comment!

Indeed, the sentence fabricating transaction objects from user intents does not mention that the result in general need not be balanced and requires that the reader already understands what transaction objects are. And, certainly, composing is the better word. Additionally, we may consider adding links to the respective pages to the specs.

[heueristik]

For application devs, an intent is an ephemeral resource being created and consumed over the course of a transaction and that express constraints over the state transition.

[heindel]

In view of this post, I would propose to avoid all forms of

• an intent is XYZ
• intents are ABC

and I think this can be done. The benefit is that we "automatically" avoid the issue to accidentally define what an intent is per se (cf. @vveiln 's post on the topic of how to not define intents, not even in the advanced section).

[heindel]

Let me summarize the points that I took away from some conversations in the meantime:

• the style of the present PR is rather fitting the advanced section
• I conjecture that the learn section is rather to be written as a sequence of tutorials How to write code for X? For example, how to write code for intents, how to write code for resources, instead of explaining the concepts that we are writing code for (which then would belong to the advanced section). Possibly, this is very much in the way described here
• the sui counterpart is rather the app-dev subsection than the whole section on concepts
• Issue What are applications (and other prerequisite concepts of the Anoma app lib)? #2 may need revision, in particular, changing from the What is X?, which is asking for the full definition, to a How to get X written in code? (or similar).

[heueristik]

Let me summarize the points that I took away from some conversations in the meantime:

• the style of the present PR is rather fitting the advanced section

I wouldn't say that. We should hide complexity a bit and present only the necessary things to developers that practically matter to them. The goal here is to give practical answers that don't break consistency with the deep-dive material (e.g. ARTs). Deep-dive material should be linked to in the advanced section.

• I conjecture that the learn section is rather to be written as a sequence of tutorials How to write code for X? For example, how to write code for intents, how to write code for resources, instead of explaining the concepts that we are writing code for (which then would belong to the advanced section). Possibly, this is very much in the way described here

I would limit tutorials to the build section.

• the sui counterpart is rather the app-dev subsection than the whole section on concepts

I don't mind. What do you propose here?

• Issue What are applications (and other prerequisite concepts of the Anoma app lib)? #2 may need revision, in particular, changing from the What is X?, which is asking for the full definition, to a How to get X written in code? (or similar).

see above