GitBook: [docs] 54 pages and 17 assets modified

knowledge_knowledge/knowledge_aquamarine/README.md

@@ -0,0 +1,30 @@
+# Aquamarine
+
+Aquamarine is a programming language and executable choreography tool for distributed applications and backends. Aquamarine manages the communication and coordination between services, devices, and APIs without introducing any centralized gateway and can be used to express various distributed systems: from simple request-response to comprehensive network consensus algorithms.
+
+At the core of Aquamarine is the design ideal and idea to pair concurrent systems, and especially decentralized networks, with a programing and execution tool chain to avoid centralized bottlenecks commonly introduced with [workflow engines](https://en.wikipedia.org/wiki/Workflow_engine) and [Business rule engines](https://en.wikipedia.org/wiki/Business_rules_engine). This not only makes Aquamarine the rosetta stone of the Fluence solution but also a very powerful generic coordination and composition medium.
+
+## Background
+
+When we build systems, we need to be able to model, specify, analyze and verify them and this is especially important to concurrent systems such as parallel and multi-threaded systems. [Formal specification](https://en.wikipedia.org/wiki/Formal_specification) are a family of formal approaches to design, model, and verify system. In the context of concurrent systems, there are two distinct formal specification techniques available. The state oriented approach is concerned with modeling verifying a systems state and state transitions and is often accomplished with [TLA+](https://en.wikipedia.org/wiki/TLA%2B). Modern blockchain design, modeling, and verification tend to rely on a state-based specification.
+
+An alternative, complementary approach is based on [Process calculus](https://en.wikipedia.org/wiki/Process_calculus) to model and verify the sequence of communications operations of a system at any given time. [π-Calculs](https://en.wikipedia.org/wiki/%CE%A0-calculus) is a modern process calculus employed in a wide range of applications ranging from biology to games and business processes.
+
+Aquamarine, Fluence's distributed composition language and runtime, is based on π-calculus and provides a solid theoretical basis toward the design, modeling, implementation, and verification of a wide class of distributed, peer-to-peer networks, applications and backends.
+
+TODO: maybe add some non-fluence examples; definitely get to the verification bit.
+
+## Language
+
+[Aquamarine Intermediate Representation](https://github.com/boneyard93501/docs/tree/a512080f81137fb575a5b96d3f3e83fa3044fd1c/src/knowledge-base/knowledge_aquamarine__air.md) \(AIR\) is a low-level language modelled after the [WebAssembly text format](https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format) and allows developers to manage network peers as well as services and backends. AIR, while intended as a compile target, is currently the only Aquamarine language implementation although a high level language \(HLL\) is currently under active development.
+
+TODO: verify below and that we don't have parallel composition proper The Aquamarine language implementation includes
+
+* sequential composition
+* reduction semantics
+* communication
+
+## Runtime
+
+The Aquamarine runtime is a virtual machine executed by the [Fluence Compute Engine](https://github.com/boneyard93501/docs/tree/a512080f81137fb575a5b96d3f3e83fa3044fd1c/src/knowledge-base/knowledge_fce.md) \(FCE\) running not only on every Fluence network peer but also on every frontend client. The distributed runtime availability per node not only aids in decentralized service discovery and execution at the same level of decentralization of the network, which is of significant importance. Moreover, with running execution scripts on both the client and the \(remote\) nodes, a high degree of auditability and verifiability can be attained.
+

knowledge_knowledge/knowledge_aquamarine/hll.md

@@ -0,0 +1,10 @@
+# HLL
+
+### Aquamarine High Level Language
+
+Since parenthesis management is a bit of a downer, we are very soon providing a high level language with AIR as the compile target. Aquamarine users, rejoice !
+
+_**Stay Tuned -- Coming Soon To A Repo Near You**_
+
+
+

knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md

@@ -0,0 +1,55 @@
+# AIR
+
+The Aquamarine Intermediate Representation \(AIR\) is a low level language to program both distributed networks and the services deployed on them. The language is comprised of five instructions:
+
+* _call_: : execution
+* _seq_ : sequential
+* _par  :_ parallel
+* _fold_ : iteration
+* _xor :_ branching & error handling
+* _null_ : empty instruction
+
+which operate on _peer-id_ \(location\), _service-id_, and _service method_ over an argument list, see Figure 1.
+
+**Figure 1: AIR Instruction Definition** ![Execution](../../.gitbook/assets/air_call_execution_1.png)
+
+## Instructions
+
+AIR instructions are intended to launch the execution of a service method as follows:
+
+1. The method is executed on the peer specified by the peer id \(location\) parameter
+2. The peer is expected to have the Wasm service specified by the service id parameter
+3. The service must have a callable method specified be the method parameter
+4. The arguments specified by the argument list are passed to the method
+5. The result of the method returned under the name output name
+
+**Figure 2: Sequential Instruction** ![Execution](../../.gitbook/assets/air_sequential_2%20%281%29%20%281%29.png)
+
+The seq instruction takes two instructions at most as its arguments and executes them sequentially, one after the other.
+
+**Figure 3: Parallel Instruction** ![Execution](../../.gitbook/assets/air_par_3.png)
+
+The par</i.> instruction takes two instructions at most as its arguments and particles may execute on parallel paths iff each service referenced is hosted on a different node otherwise particles execute sequentially
+
+TODO: add better graphic showing the disticntion of branching vs seq.
+
+**Figure 4: Fold Instruction** ![Execution](../../.gitbook/assets/air_fold_4%20%281%29.png)
+
+The fold instruction iterates over the elements of an array and workds as follows:
+
+* fold instruction takes three arguments: an array, a variable and an instruction
+* At each iteration, the variable is assigned an element of the array and the argument-instruction is executed
+* The argument-instruction can access the variable and uses the next statement to trigger the next iteration
+
+Figure 5: XOR Instruction ![Execution](../../.gitbook/assets/air_xor_5.png)
+
+This instruction is intended for organizing branches in the flow of execution as well as for handling errors:
+
+* The XOR instruction takes two instructions as its arguments
+* The first instruction is executed and if the execution is successful, then the second instruction is ignored
+* If the first instruction fails, then the second one is executed.
+
+**Figure 6: Null Instruction** ![Execution](../../.gitbook/assets/air_null_6%20%281%29.png)
+
+This is an empty instruction: it takes no arguments and does nothing. The null instruction is useful for generating code.
+

knowledge_knowledge/knowledge_aquamarine/vm.md

@@ -0,0 +1,2 @@
+# VM
+