Skip to content

Commit

Permalink
refactor: restructuring
Browse files Browse the repository at this point in the history
  • Loading branch information
@heueristik
heueristik committed Nov 12, 2024
1 parent 545df24 commit 06ffabf
Show file tree
Hide file tree
Showing 4 changed files with 115 additions and 100 deletions.
139 changes: 65 additions & 74 deletions Material/1_Learn-Anoma-Apps.md
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,31 @@
# Anoma Applications Primer

- [Anoma's State Model](#anomas-resource-model)
Anoma is a distributed operating system for intent-centric applications.

- [State Model Comparison](#state-model-comparison)
In the beginning, we introduce some of Anoma's mechanisms with a focus on app-development.

- [Anoma's State Model](#anomas-state-model)
- [Resources](#resources)
- [ Transactions](#transactions)
- [Resource Machine](#resource-machine)
- [Transactions](#transactions)
- [Anoma Resource Machine](#anoma-resource-machine)
- [Concepts](#concepts)
- [Valididty](#validity)
- [Applications](#applications)

## Anoma's State Model

Anoma is a distributed operating system for intent-centric applications.

In contrast to other protocols, it maintains state in a resource model.
Anoma organizes state in a resource model.

<p align="center">
<img alt="schematic depiction of state as resources" width="250" src="../.assets/state.png">
</p>
<p align="right">
<small>
Credit to Yulia Khalniyazova for all graphics in this document.
</small>
</p>

This enables

- Heterogeneous trust
- Resources can live on different controllers (e.g., L1's, L2's, three friends in a LAN)
- Information flow control
- Transactions can be transparent, shielded, or private -- just by setting a flag
- Intent-level Composability
- Intents (unbalanced transactions) can be composed and settled across different applications and chains

### State Model Comparison
<details><summary><b>Comparison to other State Models</b></summary>

Comparing the resource model to other state models, the advantages become clear.

Expand All @@ -41,7 +36,7 @@ Comparing the resource model to other state models, the advantages become clear.
</p>

- State is explict and global
- Example: A ethereum smart contract containing value (e.g., `uint256`) or a account balance mapping (`mapping(address => uint256)`) in an Ethereum smart contract.
- Example: An Ethereum smart contract containing value (e.g., `uint256 count`) or a account balance mapping (`mapping(address => uint256) balanceOf`).
- An application must be deployed to each chain specifically.
- Cross-chain apps require sophisticated bridging and code changes.

Expand All @@ -54,7 +49,7 @@ Comparing the resource model to other state models, the advantages become clear.
- State is implicit and comprised of all unspent transaction outputs (UTXOs)
- Examples: Bitcoin or Zcash transactions
- The predicate determining if it is allowed to spent an UTXO is always the same
- Arbitrary applications are difficult/not possible.
- Arbitrary applications are difficult/not possible

#### Resource Model

Expand All @@ -63,23 +58,40 @@ Comparing the resource model to other state models, the advantages become clear.
</p>

- State is implicit and comprised of all unspent resources
- Predicates attached to resources can be arbitrary, which enables aribtrary applications and general intents.
- Predicates and data attached to resources can be arbitrary
- Arbitrary applications and general intents are enabled

</details>

### Affordances

This enables[^cwgoes]

[^cwgoes]: https://ethresear.ch/t/rfc-draft-anoma-as-the-universal-intent-machine-for-ethereum/19109.

- Heterogeneous trust
- Resources can live on different controllers (e.g., L1's, L2's, three friends in a LAN).
- A transaction can consume a resource on controller A and create it on controller B.
- Information flow control
- Transactions can be sent transparent, shielded, or private just by setting a flag
- Intent-level Composability
- Intents (unbalanced transactions) can be composed and settled across different applications and chains

## Resources

**Resources** are atomic units of application state and logic. They have

- data (e.g, owner, diameter, age)
- have a logic function enforcing predicates (that check data, e.g., in other resources)
- have a quantity, a label, and a specific kind
- a quantity, label, and specific kind
- data (e.g, owner, diameter, etc.)
| 5 🐚 `{diameter : 1.4}` | 2 🍏 `{fruitiness : 8 / 10}` | 1 💌 `{text : "I ❤️ u"}` |
|:--------------------------------:|:-----------------------------:|:---------------------------------:|
| `5 Shell` resource | `2 Apple` resource | `1 Message` Resource |
- have a lifecycle with three stages,
| `5 Shell` resource | `2 GreenApple` resource | `1 Message` Resource |
- a lifecycle with three stages,
```mermaid
flowchart LR
Non-existent --> Created --> Consumed
```
- a logic function enforcing predicates (that check data, e.g., in itself, the transaction or other resources)

<details><summary><b>The <code>Resource</code> object in detail</b></summary>

Expand Down Expand Up @@ -109,6 +121,19 @@ type Resource :=
*Types named `*Ref` are binding references to objects in BLOB storage.

</details>
<p></p>

**Creation:** To create a resource its _commitment_ must be computed by hashing the resource object.
$$\texttt{commitment} := h_\texttt{cm}(\texttt{resource})$$
After execution, the commitment is added to a Merkle tree.

**Consumption:** To consume a resource its _nullifier_ must be computed by hashing the resource object and a secret called the _nullifier key_.
$$\texttt{nullifier} := h_\texttt{nf}(\texttt{resource},\,\texttt{nullifierKey})$$
After execution, the nullifier is added into a nullifier set.

**Kind:** The _kind_ of a resource determines its fungibility and is computed as the hash of its _logic_ and _label_.
$$\texttt{kind} := h_\texttt{kind}(\texttt{logic},\,\texttt{label})$$
The kind is used to check if transactions are balanced.

## Transactions

Expand All @@ -120,13 +145,13 @@ type Resource :=
- An unbalanced transaction is called **intent**.
- Only balanced and transactions can be executed

| Consumed | Created | Balanced? |
| :-------------------: | :-------------------: | :-------: |
| 2🍏 | 2🍏 | ✅ |
| 2🍏 | 1🍏 + 1🍏 | ✅ |
| 2🍏 + 1🐚 | 1🍏 + 2🐚 | ❌ |
| 2🍏 + 1🐚 | 1🍏 + 1🍎 + 1🐚 | ❌ |
| 1🍏 + 2🍎 + 2🍎 + 3🐚 | 1🍏 + 4🍎 + 1🐚 + 2🐚 | ✅ |
| Consumed | Created | Balanced? ✅/❌ |
| :-------------------: | :-------------------: | :-------------: |
| 2🍏 | 2🍏 | |
| 2🍏 | 1🍏 + 1🍏 | |
| 2🍏 + 1🐚 | 1🍏 + 2🐚 | |
| 2🍏 + 1🐚 | 1🍏 + 1🍎 + 1🐚 | |
| 1🍏 + 2🍎 + 2🍎 + 3🐚 | 1🍏 + 4🍎 + 1🐚 + 2🐚 | |

- contain **actions** for context separation.

Expand Down Expand Up @@ -163,31 +188,20 @@ type Action :=

## Anoma Resource Machine

The [**Anoma Resource Machine** (ARM)](#resource-machine) is a virtual machine being part of the Anoma Protocol and checks if transactions are adhering to its rules and are therefor [valid](#validity).

### Concepts

- **Creation:** To create a resource its _commitment_ must be computed by hashing the resource object.
$$\texttt{commitment} := h_\texttt{cm}(\texttt{resource})$$

- **Consumption:** To consume a resource its _nullifier_ must be computed by hashing the resource object and a secret called the _nullifier key_.
$$\texttt{nullifier} := h_\texttt{nf}(\texttt{resource},\,\texttt{nullifierKey})$$

- **Kind:** The _kind_ of a resource determines its fungibility and is computed as the hash of its _logic_ and _label_.
$$\texttt{kind} := h_\texttt{kind}(\texttt{logic},\,\texttt{label})$$
The [**Anoma Resource Machine** (ARM)](#resource-machine) is a virtual machine being part of the Anoma Protocol and checks if transactions are adhering to its rules and are therefore [valid](#validity).

### Validity

1. **Balance check:** The number of consumed and created resources of the same kind must balance in a transaction.
2. **Resource Logic Checks:** For each resource in the transaction, the corresponding resource logic function must return `true`.
3. **Resource Machine Compliance Checks:** Ensures the RM rules are met.
3. **Compliance Checks:** Ensures the RM rules are met.
- Created resources
- Commitments can not exist already.
- Consumed resources
- Commitment must exist already
- Nullifier can not exist
- Ephemeral resources (created and consumed)
- existence checks are skipped.
- existence checks are skipped

## Applications

Expand All @@ -204,12 +218,13 @@ Instead of creating and consuming resources and providing all data required in t

The interface consists of

- Transaction function (the application write interface)
- Outputs a transaction object
- Example: Transfer of a resource to a new owner.
- Projection functions (the application read interface)
- Projection functions (the application **read interface**)
- Outputs meaningful data projected from the state
- Example: The total quantity of resources of specific kind owned by an identity
- Transaction function (the application **write interface**)
- Outputs a transaction object
- Example: Transfer of a resource to a new owner.


```mermaid
flowchart TB
Expand All @@ -230,27 +245,3 @@ flowchart TB
```

</details>

### Kudos Token

Accounting primitive for applications

#### Feature Set

- Identifiers (name, symbol, decimals)
- Orignator
- Can initially create new quantities of this kind/
- Supply
- Fixed: The total quantity of resources of this kind is fixed. Resources can still be split and merged.
- Capped: Upper bound on the total quantity. Originator cannot create more than this limit. Owners can burn tokens,
- Unbound: Originator can inflate the supply.
- Transferability
- Transferable: Your normal token (ERC-20, NFT)
- Non-transferable: Soulbound token (SBT)

#### `Token` Implementation

- Resource Label: [1](https://github.com/anoma/anoma-applib/blob/a6c4993f203d759051ef4a31c0c6c7fde0a9e9a2/Applib/Token/Label.juvix#L8-L16),[2](../HelloWorld/.juvix-build/0.6.8/deps/c4c0b1e74196bd1135c8ea27b48f6756d7ec7aa8f5388511e02d6401d1f1c407/Applib/Token/Label.juvix)
- Resource Logic Function: [1](https://github.com/anoma/anoma-applib/blob/a6c4993f203d759051ef4a31c0c6c7fde0a9e9a2/Applib/Token/Logic.juvix#L13-L23),[2](../HelloWorld/.juvix-build/0.6.8/deps/c4c0b1e74196bd1135c8ea27b48f6756d7ec7aa8f5388511e02d6401d1f1c407/Applib/Token/Logic.juvix)
- Transaction functions (write interface): [1](https://github.com/anoma/anoma-applib/blob/a6c4993f203d759051ef4a31c0c6c7fde0a9e9a2/Applib/Transaction),[2](../HelloWorld/.juvix-build/0.6.8/deps/c4c0b1e74196bd1135c8ea27b48f6756d7ec7aa8f5388511e02d6401d1f1c407/Applib/Transaction)
- Projection functions (read interface): [1](https://github.com/anoma/anoma-applib/blob/a6c4993f203d759051ef4a31c0c6c7fde0a9e9a2/Applib/Projection/TotalQuantity.juvix#L9-L12),[2](../HelloWorld/.juvix-build/0.6.8/deps/c4c0b1e74196bd1135c8ea27b48f6756d7ec7aa8f5388511e02d6401d1f1c407/Applib/Projection/TotalQuantity.juvix)
19 changes: 8 additions & 11 deletions Material/2_Install-Juvix.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,18 @@
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/anoma/juvix-workshop?quickstart=1)

## Table of Contents

- [Introduction](#introduction)
- [Installing Juvix](#installing-juvix)
- [IDE Setup](#ide-setup)
- [VSCode](#vscode)
- [Emacs](#emacs)
- [VSCode](#vscode)
- [Emacs](#emacs)
- [Juvix Documentation](#juvix-documentation)


## Introduction

Welcome to Juvix!



## Installing Juvix

Please use one of the following options to install the Juvix compiler. Juvix is
Expand All @@ -35,7 +33,7 @@ The Juvix compiler requires [the LLVM/clang compiler](https://llvm.org) to be av

If you use the [Homebrew package manager](https://brew.sh) you can use our tap:

``` shell
```shell
brew update
brew tap anoma/juvix
brew install juvix
Expand All @@ -45,7 +43,7 @@ brew install juvix

To install for linux or macOS run the following in a terminal (as a non-root user):

``` shell
```shell
curl --proto '=https' --tlsv1.2 -sSfL https://get.juvix.org | sh
```

Expand All @@ -54,7 +52,7 @@ curl --proto '=https' --tlsv1.2 -sSfL https://get.juvix.org | sh
There are also binaries for the Juvix compiler available to download

| OS / Architecture |
|-------------------------------------------------------------------------------------------------------------|
| ----------------------------------------------------------------------------------------------------------- |
| [Linux x86_64](https://github.com/anoma/juvix/releases/latest/download/juvix-linux-x86_64.tar.gz) |
| [macOS x86_64](https://github.com/anoma/juvix/releases/latest/download/juvix-macos-x86_64.tar.gz) |
| [macOS aarch64 (M1/M2)](https://github.com/anoma/juvix/releases/latest/download/juvix-macos-aarch64.tar.gz) |
Expand All @@ -73,13 +71,13 @@ See the [vscode-juvix repository](https://github.com/anoma/vscode-juvix) for usa

To get started, clone the [juvix-mode repository](https://github.com/anoma/juvix-mode.git)

``` shell
```shell
git clone https://github.com/anoma/juvix-mode.git
```

And add the following lines to your Emacs configuration file:

``` emacs-lisp
```emacs-lisp
(push "/path/to/juvix-mode/" load-path)
(require 'juvix-mode)
```
Expand All @@ -89,4 +87,3 @@ See the [juvix-mode repository](https://github.com/anoma/juvix-mode.git) for usa
## Juvix Documentation

The full documentation for Juvix is available at https://docs.juvix.org

52 changes: 40 additions & 12 deletions Material/3_Write-Applications.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Writing Applications
# Write & Explore Applications

## Write your first Application

If you [installed Juvix](./2_Install-Juvix.md) on you machine, clone this repo

Expand All @@ -16,17 +18,43 @@ or go to [github.com/anoma/applications-workshop](https://github.com/anoma/appli

Go through the folders `Excercise_X` and find the assignments as comments inside the `.juvix` files.

| Command | Description |
| :------ | :---------- |
| | |
| Command | Description |
| :-------------------------- | :-------------------------------------------------------------------- |
| `juvix clean --global` | Delete your juvix dependencies |
| `juvix clean` | Delete build artifacts |
| `juvix dependencies update` | Fetch & update the dependencies specified in the `Package.juvix` file |
| `juvix typecheck` | Check your app for type errors. |
| `juvix format --in-place` | Format your files |

Do it all at once with

```sh
juvix clean --global && juvix clean && juvix dependencies update && juvix typecheck && juvix format --in-place
```

## Explore the Kudos Token

Kudos is an accounting primitive for Anoma. Kudos intents can embody trust relationships between identities.

### Feature Set

- `juvix clean --global` : Delete your juvix dependencies.
- `juvix clean` : Delete build artifacts
- `juvix dependencies update`: Fetch & update the dependencies specified in the `Package.juvix` file.
- `juvix typecheck` : Check your app for type errors.
- `juvix format --in-place` : Format your files.
- Identifiers (name, symbol, decimals)
- Originator
- Can initially create new quantities of this kind/
- Supply
- Fixed: The total quantity of resources of this kind is fixed. Resources can still be split and merged.
- Capped: Upper bound on the total quantity. Originator cannot create more than this limit. Owners can burn tokens,
- Unbound: Originator can inflate the supply.
- Transferability
- Transferable: Your normal token (ERC-20, NFT)
- Non-transferable: Soulbound token (SBT)
- Interface
- mint, burn, transfer, split, merge (no counterparty required)
- swap intent (counterparty required)

- Do it all at once with :
- `juvix clean --global && juvix clean && juvix dependencies update && juvix typecheck && juvix format --in-place`
### `Token` Implementation

Finally, we will look at the current `Token` implementation.
- Resource Label: [1](https://github.com/anoma/anoma-applib/blob/a6c4993f203d759051ef4a31c0c6c7fde0a9e9a2/Applib/Token/Label.juvix#L8-L16),[2](../HelloWorld/.juvix-build/0.6.8/deps/c4c0b1e74196bd1135c8ea27b48f6756d7ec7aa8f5388511e02d6401d1f1c407/Applib/Token/Label.juvix)
- Resource Logic Function: [1](https://github.com/anoma/anoma-applib/blob/a6c4993f203d759051ef4a31c0c6c7fde0a9e9a2/Applib/Token/Logic.juvix#L13-L23),[2](../HelloWorld/.juvix-build/0.6.8/deps/c4c0b1e74196bd1135c8ea27b48f6756d7ec7aa8f5388511e02d6401d1f1c407/Applib/Token/Logic.juvix)
- Transaction functions (write interface): [1](https://github.com/anoma/anoma-applib/blob/a6c4993f203d759051ef4a31c0c6c7fde0a9e9a2/Applib/Transaction),[2](../HelloWorld/.juvix-build/0.6.8/deps/c4c0b1e74196bd1135c8ea27b48f6756d7ec7aa8f5388511e02d6401d1f1c407/Applib/Transaction)
- Projection functions (read interface): [1](https://github.com/anoma/anoma-applib/blob/a6c4993f203d759051ef4a31c0c6c7fde0a9e9a2/Applib/Projection/TotalQuantity.juvix#L9-L12),[2](../HelloWorld/.juvix-build/0.6.8/deps/c4c0b1e74196bd1135c8ea27b48f6756d7ec7aa8f5388511e02d6401d1f1c407/Applib/Projection/TotalQuantity.juvix)
5 changes: 2 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@

<p align="right">
<img alt="anoma logo" width="200" src="./.assets/anoma-logo.png">
</p>
<h1> Applications Workshop </h1>

Welcome to the Anoma Applications Workshop!

In this workshop we will
In this workshop we will

1. [Learn](./Material/1_Learn-Anoma-Apps.md) about [Anoma](https://anoma.net/) and intent-centric apps.
2. [Install](./Material/2_Install-Juvix.md) the [Juvix](https://juvix.org/) language (**optional**), a language for intent-centric and declarative decentralized apps.
3. [Write](./Material/3_Write-Applications.md) & explore Anoma apps.
3. [Write](./Material/3_Write-Applications.md#write-your-first-application) & [explore](./Material/3_Write-Applications.md#explore-the-kudos-tokens) Anoma apps.

0 comments on commit 06ffabf

Please sign in to comment.