diff --git a/Material/1_Learn-Anoma-Apps.md b/Material/1_Learn-Anoma-Apps.md index c48fa9c..f441c4a 100644 --- a/Material/1_Learn-Anoma-Apps.md +++ b/Material/1_Learn-Anoma-Apps.md @@ -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.

schematic depiction of state as resources

+

+ +Credit to Yulia Khalniyazova for all graphics in this document. + +

-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 +
Comparison to other State Models Comparing the resource model to other state models, the advantages become clear. @@ -41,7 +36,7 @@ Comparing the resource model to other state models, the advantages become clear.

- 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. @@ -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 @@ -63,23 +58,40 @@ Comparing the resource model to other state models, the advantages become clear.

- 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 + +
+ +### 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)
The Resource object in detail @@ -109,6 +121,19 @@ type Resource := *Types named `*Ref` are binding references to objects in BLOB storage.
+

+ +**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 @@ -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. @@ -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 @@ -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 @@ -230,27 +245,3 @@ flowchart TB ``` - -### 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) diff --git a/Material/2_Install-Juvix.md b/Material/2_Install-Juvix.md index 02a952a..e69f4c7 100644 --- a/Material/2_Install-Juvix.md +++ b/Material/2_Install-Juvix.md @@ -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 @@ -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 @@ -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 ``` @@ -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) | @@ -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) ``` @@ -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 - diff --git a/Material/3_Write-Applications.md b/Material/3_Write-Applications.md index 75bc7c6..09dd315 100644 --- a/Material/3_Write-Applications.md +++ b/Material/3_Write-Applications.md @@ -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 @@ -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) diff --git a/README.md b/README.md index 2a2c159..3df5531 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ -

anoma logo

@@ -6,8 +5,8 @@ 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.