Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: initial learn section #3

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Empty file added .gitbook/assets/image (1).png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Empty file added .gitbook/assets/image.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 10 additions & 2 deletions SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,18 @@

* [Anoma Overview](README.md)

## Build

## LEARN

* [Overview](learn/overview.md)
* [What is Anoma?](learn/what-is-anoma/README.md)
* [What is an intent?](learn/what-is-anoma/what-is-an-intent.md)
* [What is a resource?](learn/what-is-anoma/what-is-a-resource.md)
* [What is a resource logic?](learn/what-is-anoma/what-is-a-resource-logic.md)
* [What is a transaction?](learn/what-is-anoma/what-is-a-transaction.md)
* [Anoma Applications](learn/anoma-applications/README.md)
* [What is an Anoma application?](learn/anoma-applications/what-is-an-anoma-application.md)
* [What is application state?](learn/anoma-applications/what-is-application-state.md)

## Advanced

* [Advanced](advanced/advanced.md)
10 changes: 10 additions & 0 deletions learn/anoma-applications/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
description: >-
From an end-user perspective, applications are what makes the intent-machine
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

run. The space of applications is wide open and here we mainly focus on
applications as a general concept.
icon: hammer-brush
---

# Anoma Applications

19 changes: 19 additions & 0 deletions learn/anoma-applications/what-is-an-anoma-application.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# What is an Anoma application?

An Anoma _application_ is a set of resource kinds and solvers. Resource kinds allow to narrow down the fragments of state that are of interest to an application; then, the solvers of an application operate on (this fragment of) state, which typically involves combining user intents into transaction objects. Thus, solvers are what makes the intent-machine work for all users. In fact, there is potentially a whole system of applications as applications may interact (directly) with each other whenever they operate on resources of the same kind. 
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


### Resource kind

The resource kind fixes the resource logic and additional information that every resource of this kind carries; in this way, set of standard resource logics can be re-used for different resource kinds with similar behaviour.

### Solver

A solver is a specific user that is fabricating transaction objects from user intents such that the preferences for state (change) of intents are effected by state updates.
Copy link
Collaborator Author

@heueristik heueristik Oct 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


### Application read interface: projection functions

Projection functions constitute the application read interface: solvers use projection functions to read relevant fragments of state kept by the Anoma instance. 

### Application write interface: transaction functions

Transaction functions constitute the application write interface: solvers use transaction functions to update the state that is maintained by the Anoma instance. 
3 changes: 3 additions & 0 deletions learn/anoma-applications/what-is-application-state.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# What is application state?

For applications, the core fragment of state are all resources that are known to exist and information about which ones are still spendable. Each application typically uses only a small number of resource kinds.
13 changes: 13 additions & 0 deletions learn/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
icon: globe
---

# Overview

There are several perspectives on Anoma. We start by looking from the perspective of the _end-user_ and then move progressively to the perspective of application development.

<div data-full-width="true">

<figure><img src="../.gitbook/assets/image (1).png" alt=""><figcaption></figcaption></figure>

</div>
7 changes: 7 additions & 0 deletions learn/what-is-anoma/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
icon: wand-magic-sparkles
---

# What is Anoma?

Anoma is an [intent-machine](https://anoma.net/research/abstract-intent-machines): in short, an intent-machine takes user intents and turns them into transactions that are settled so that the state actually changes according to user preferences expressed by intents. But what is an intent?
3 changes: 3 additions & 0 deletions learn/what-is-anoma/what-is-a-resource-logic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# What is a resource logic?

A _resource logic_ describes the ways in which a resource can be used, in Anoma at large; it fixes precise conditions for creation and destruction of resources that carry it. Resource logics can be programmed in Juvix as Boolean valued functions.
3 changes: 3 additions & 0 deletions learn/what-is-anoma/what-is-a-resource.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# What is a resource?

A _resource_ is an atomic unit of state. Resources are similar to [unspent transaction outputs](https://en.wikipedia.org/wiki/Unspent\_transaction\_output), but much more versatile. In particular, each resource carries a generic resource logic, which describes the ways in which the resource may be used.
4 changes: 4 additions & 0 deletions learn/what-is-anoma/what-is-a-transaction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# What is a transaction?

A transaction object is data that enables a state update that is acceptable according to the [Anoma resource machine](https://anoma.net/research/rise-of-the-resource-machines); each state update amounts to execution of one or several transaction objects. While it is possible to directly create and submit transaction objects to an Anoma instance, the main idea to consider Anoma as an intent-machine is that transactions are composed of user intents. One way in which intents are turned into transactions is in the context of Anoma applications.

16 changes: 16 additions & 0 deletions learn/what-is-anoma/what-is-an-intent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# What is an intent?

An _intent_ is a machine-readable message concerning user preferences about state. Thus, users can send intents to spread information about how they would like to change (certain aspects of) the "world". The "world" of an application is the application's _state._
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).


***

Note that

> intents only care about the “what” and don’t care about the “how.”

The above quote is taken from the medium article [WTF is intents?](https://medium.com/@wunderlichvalentin/wtf-is-intents-anoma-th-ccb05fa1beef)&#x20;