Heindel/rm overview dag v03

.github/workflows/pull-requests.yml

@@ -78,7 +78,7 @@ jobs:
           cache: enable
           rename-to: juvix
           chmod: 0755
-      - uses: actions/cache@v4.0.2
+      - uses: actions/cache@v4
         with:
           key: juvix-cache-${{ hashFiles('**/*.juvix.md') }}-${{ hashFiles('**/*.juvix') }}
           path: .juvix-build
@@ -106,14 +106,14 @@ jobs:
           poetry config virtualenvs.in-project true --local
       - run: echo "cache_id=$(date --utc '+%V')-${{ hashFiles( '**/poetry.lock' )}}-${{ hashFiles( '**/*.py' )}}" >> $GITHUB_ENV
       - name: Cache .cache
-        uses: actions/cache@v4.0.2
+        uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache
           restore-keys: |
             mkdocs-material-
       - name: Cache .cache-juvix-mkdocs
-        uses: actions/cache@v4.0.2
+        uses: actions/cache@v4
         with:
           key: .cache-juvix-mkdocs-${{ env.cache_id }}
           path: .cache-juvix-mkdocs

VERSION

@@ -1 +1 @@
-v0.1.4
+v0.3

docs/arch/system/state/resource_machine_03/dag.puml

@@ -0,0 +1,3 @@
+@startuml
+Bob -> Alice : [[https://research.anoma.net Forums]]
+@enduml

docs/arch/system/state/resource_machine_03/dag.txt

@@ -0,0 +1,275 @@
+classDiagram
+    %% Core Interfaces
+    class IProvingSystem~VerifyingKey,ProvingKey,Instance,Witness,Proof~ {
+        +prove(ProvingKey, Instance, Witness) Proof
+        +verify(VerifyingKey, Instance, Proof) Bool
+    }
+    %%IProvingSystem done.
+    %%ProvingSystem done.
+    class IDeltaProvingSystem~VerifyingKey,ProvingKey,Instance,Witness,Proof~ {
+        +aggregate(Proof, Proof) Proof
+    }
+    class ISet~T~ {
+        +new() Set
+        +new(List) Set
+        +size(Set) Nat
+        +insert(Set, T) Set
+        +union(Set, Set) Set
+        +intersection(Set, Set) Set
+        +difference(Set, Set) Set
+        +disjointUnion(Set, Set) Set
+        +contains(Set, T) Bool
+    }
+    class IOrderedSet~T~
+    class FixedSize~T,Arg~ {
+        +bit_size: Int
+        +new(Arg) T
+        +equal(T, T) Bool
+    }
+    %%Arithmetic done.
+    class Arithmetic~T,Arg~ {
+        +add(T, T) T
+        +sub(T, T) T
+    }
+    class Hash~T,Arg~
+    class CommitmentAccumulator~Witness,CommitmentIdentifier,AccumulatedValue~ {
+        +add(Accumulator, CommitmentIdentifier) Witness
+        +witness(Accumulator, CommitmentIdentifier) Maybe Witness
+        +verify(CommitmentIdentifier, Witness, AccumulatedValue) Bool
+        +value(Accumulator) AccumulatedValue
+    }
+    class NullifierSet
+
+    %% Core Data Structures
+    %%Resource done.
+    class Resource {
+        +logicRef: LogicHash
+        +labelRef: LabelHash
+        +valueRef: ValueHash
+        +quantity: Quantity
+        +isEphemeral: Bool
+        +nonce: Nonce
+        +nullifierKeyCommitment: NullifierKeyCommitment
+        +randSeed: RandSeed
+        +commitment() Commitment
+        +nullifier(NullifierKey) Nullifier
+        +kind() Kind
+        +delta() DeltaHash
+        +tag(consumed: Bool) Tag
+    }
+    class Action {
+        +created: List Commitment
+        +consumed: List Nullifier
+        +resourceLogicProofs: Map Tag (LogicRefHash, PS.Proof)
+        +complianceUnits: Set ComplianceUnit
+        +applicationData: Map Tag (BitString, DeletionCriterion)
+        +verify() Bool
+        +delta() DeltaHash
+    }
+    class ComplianceUnit {
+        +proof: PS.Proof
+        +refInstance: ReferencedInstance
+        +vk: PS.VerifyingKey
+        +delta() DeltaHash
+        +verify() Bool
+    }
+    class Transaction {
+        +CMTreeRoots: Set CMtree.Value
+        +actions: Set Action
+        +deltaProof: DeltaProvingSystem.Proof
+        +create(Set CMtree.Value, Set Actions) Transaction
+        +compose(Transaction, Transaction) Transaction
+        +verify() Bool
+        +delta() DeltaHash
+    }
+    %%Transaction done.
+
+    %% Implementation Classes
+    class ResourceLogicProvingSystem
+    class ComplianceProvingSystem
+    class DeltaProvingSystem
+    class OrderedSet
+    class CMTree
+    class NFSet
+    class DeltaHash
+    class TransactionFunction {
+        +eval() Transaction
+    }
+    class TransactionFunctionVM {
+        +eval(TransactionFunction, GasLimit) Transaction
+    }
+    class TransactionWithPayment {
+        +stateTransitionFunction: TransactionFunction
+        +paymentTransaction: Transaction
+        +gasLimit: Arithmetic
+    }
+
+    %% Fixed Size Types
+    class Nonce
+    class RandSeed
+    class NullifierKeyCommitment
+    class NullifierKey
+    class Quantity
+    class Balance
+    class LogicHash
+    class LabelHash
+    class ValueHash
+    class Commitment
+    class Nullifier
+    class LogicRefHash
+
+    %% Proof Related Types
+    class ResourceLogicProofInstance {
+        +tag: Tag
+        +isConsumed: Bool
+        +consumed: List Nullifier
+        +created: List Commitment
+        +applicationData: BitString
+    }
+    class ResourceLogicProofWitness {
+        +consumed: OrderedSet (Resource, NullifierKey)
+        +created: OrderedSet Resource
+        +applicationInputs: Any
+    }
+    class ComplianceProofInstance {
+        +consumed: List (NullifierRef, RootRef, LogicRefHash)
+        +created: List (CommitmentRef, LogicRefHash)
+        +unitDelta: DeltaHash
+    }
+    class ComplianceProofWitness {
+        +consumed: OrderedSet Resource
+        +consumed_nullifierKey: OrderedSet NullifierKey
+        +consumed_cmtreePath: OrderedSet CMtreePath
+        +consumed_commitment: OrderedSet Commitment
+        +consumed_logicRefHash: OrderedSet LogicRefHash
+        +created: OrderedSet Resource
+        +created_logicRefHash: OrderedSet LogicRefHash
+    }
+    class DeltaProofInstance {
+        +delta: DeltaHash
+        +expectedBalance: Balance
+    }
+    class DeltaProofWitness {
+        +resourceDeltaPreimages: List Resource
+    }
+
+    %% Inheritance/Implementation
+    IProvingSystem --|> IDeltaProvingSystem
+    IProvingSystem --|> ResourceLogicProvingSystem
+    IProvingSystem --|> ComplianceProvingSystem
+    IDeltaProvingSystem --|> DeltaProvingSystem
+    ISet --|> IOrderedSet
+    IOrderedSet --|> OrderedSet
+    CommitmentAccumulator --|> CMTree
+    Timestamp --> CMTree
+    NFSet --|> NullifierSet
+    FixedSize --|> Hash
+    FixedSize --|> Arithmetic
+    Hash --|> DeltaHash
+    Arithmetic --|> DeltaHash
+
+    LogicHash --> Resource
+    LabelHash --> Resource
+    ValueHash --> Resource
+    Quantity --> Resource
+    Nonce --> Resource
+    NullifierKeyCommitment --> Resource
+    RandSeed --> Resource
+    Commitment --> Resource
+    Nullifier --> Resource
+    class Kind
+    Kind --> Resource
+    DeltaHash --> Resource
+    Tag --> Resource
+    Kind --> Resource
+
+    Resource --> ComplianceProofWitness
+    Resource --> NullifierSet
+    Resource --> DeltaProofWitness
+
+    %% Action Componenents
+    Commitment --> Action
+    Nullifier --> Action
+    Tag --> Action
+    IProvingSystem --> Action
+    LogicRefHash --> Action
+    DeletionCriterion --> Action
+    ComplianceUnit --> Action
+
+    %% Action interface reqs
+    DeltaHash --> Action
+    NullifierKey --> Action
+    Resource --> Action
+
+    IProvingSystem --> ComplianceUnit
+    %%ReferencedInstance --> ComplianceUnit
+    Commitment --> ComplianceUnit
+    Nullifier --> ComplianceUnit
+    DeltaHash --> ComplianceUnit
+
+    Action --> Transaction
+    CMTree --> Transaction
+    DeltaProvingSystem --> Transaction
+    DeltaHash --> Transaction
+
+    Transaction --> TransactionFunction
+    TransactionFunction --> TransactionWithPayment
+    Transaction --> TransactionWithPayment
+    Arithmetic --> TransactionWithPayment
+    TransactionFunction --> TransactionFunctionVM
+
+    OrderedSet --> ComplianceProofWitness
+
+    Nullifier --> ComplianceProofInstance
+    CMTree --> ComplianceProofInstance
+    LogicRefHash --> ComplianceProofInstance
+    Commitment --> ComplianceProofInstance
+
+    CMTree --> ComplianceProofWitness
+    NullifierKey --> ComplianceProofWitness
+    Commitment --> ComplianceProofWitness
+    LogicRefHash --> ComplianceProofWitness
+
+    Predicate --> DeletionCriterion
+
+    CMTree --> Transaction
+    NullifierSet --> Transaction
+    Action --> Transaction
+    DeltaHash --> Transaction
+
+    %% Fixed Size Type Implementation Dependencies
+    Hash --> LogicHash
+    Hash --> LabelHash
+    Hash --> ValueHash
+    Hash --> Commitment
+    Hash --> Nullifier
+    Hash --> Kind
+    Hash --> LogicRefHash
+    Hash --> CMTree
+
+    Arithmetic --> Quantity
+    Arithmetic --> Balance
+
+    FixedSize --> Nonce
+    FixedSize --> RandSeed
+    FixedSize --> NullifierKeyCommitment
+    FixedSize --> NullifierKey
+
+    Balance --> DeltaProofInstance
+    DeltaHash --> DeltaProofInstance
+    NullifierKey --> Nullifier
+
+    %% Input relationships (required for ResourceLogicProofInstance)
+    Tag --> ResourceLogicProofInstance
+    Nullifier --> ResourceLogicProofInstance
+    Commitment --> ResourceLogicProofInstance
+    Action --> ResourceLogicProofInstance
+    Resource --> ResourceLogicProofInstance
+
+    %% Output relationships (where ResourceLogicProofInstance is used)
+    ResourceLogicProofInstance --> ResourceLogicProvingSystem
+
+    %% Input relationships (required for ResourceLogicProofWitness)
+    OrderedSet --> ResourceLogicProofWitness
+    NullifierKey --> ResourceLogicProofWitness
+    Resource --> ResourceLogicProofWitness

docs/arch/system/state/resource_machine_03/index.juvix.md

@@ -0,0 +1,58 @@
+---
+icon: material/file-document-outline
+search:
+  exclude: false
+  boost: 2
+tags:
+  - resource-machine
+  - protocol
+  - commitment
+  - nullifier
+  - accumulator
+  - resource logic
+---
+
+```juvix
+module arch.system.state.resource_machine_03.index;
+```
+
+# Introduction
+
+The resource machine provides the default interfaces
+that controllers can use to perform state changes.
+
+```kroki-plantuml
+@from_file:./arch/system/state/resource_machine_03/rm-overview-diagram.puml
+```
+
+<!--
+**The Anoma Resource Machine (ARM)** is the part of the Anoma protocol that defines and enforces the rules for valid state updates that satisfy users' preferences. The new proposed state is then agreed on by the consensus participants. In that sense the role of the Anoma Resource Machine in the Anoma protocol is similar to the role of the Ethereum Virtual Machine in the Ethereum protocol.
+
+## Data structures
+
+The atomic unit of the ARM state is called a [[Resource | **resource**]]. Resources are immutable, they can be created once and consumed once. The system state is represented by the set of active resources: the resources that were created but not nullified.
+
+[[Transaction | **Transactions**]] produced by the ARM represent the proposed state update. They consist of [[Action|**actions**]], which group resources with the same execution context.
+
+Ensuring the correctness of the transaction is achieved with the help of non-interactive proofs attached to it:
+
+1. to prove the transaction is balanced correctly, there are [[Delta proof | delta proofs]]. Balance is the criterion of a transaction's completeness.
+2. to prove the transaction complies with the ARM rules, there are [[Compliance proof | compliance proofs]]. Actions are partitioned into [[Compliance unit | compliance units]] that define the compliance proof scope.
+3. to prove the transaction satisfies the user constraints, there are [[Resource logic proof | resource logic proofs]].
+
+
+![Proof contexts associated with data structures](proof_contexts.svg)
+
+
+## The role of the ARM
+
+The ARM is used to create, compose, and verify transactions. It is stateless and run by every node that processes transactions. Anoma users submit their intents to the intent gossip network in the form of unbalanced ARM transactions with metadata, which are received and processed by solvers that output balanced ARM transactions. These transactions are then ordered and finally sent to the executor node, that verifies and executes the transactions in the determined order, updating the global state.
+
+## The specification
+
+This specification describes a common interface shared by all ARM instantiations. Depending on the primitive instantiation choices, the resulting ARM instantiation will have different properties. For example, using zk-SNARKs to create and verify the ARM proofs might result in a succinct or even shielded ARM instantiation. The ARM interface is designed to provide interoperability between different ARM instantiations.
+
+The design of the Anoma Resource Machine was significantly inspired by the [Zcash protocol](https://zips.z.cash/protocol/protocol.pdf).
+
+- Keywords: anoma, blockchain technology, protocol design, resource machine
+-->