Merge pull request #54 from mlabs-haskell/uhbif19/update-soa-examples

Update SoA docs

docs/goals_and_soa.md

@@ -54,6 +54,8 @@ what we use to demonstrate problems in following:
   * CNS
   * Hydra
 * Plutonomicon patterns
+* Plutus tutorial
+  * [Game Model](https://github.com/IntersectMBO/plutus-apps/blob/dbafa0ffdc1babcf8e9143ca5a7adde78d021a9a/doc/plutus/tutorials/GameModel.hs)
 * plutus-usecases
 
 @todo #3: Add more links to specific bugs and code size blowups in existing DApps.
@@ -98,6 +100,9 @@ eliminate some constraint following from others.
 Such kind of manual SMT solving exercises are
 known source for security bugs and complicated code.
 
+Checking such constraints leads to code bloat
+in form of bunch of utility functions.
+
 Making Plutus contract invariant to `TxIn` ordering
 and participation in multi-script scenarios lead to
 similar kind of complications.
@@ -107,6 +112,8 @@ Examples:
 * Non-security bug: https://github.com/mlabs-haskell/hydra-auction/issues/129
 * Non-security bug: https://github.com/mlabs-haskell/hydra-auction/commit/8152720c43732f8fb74181b7509de503b8371997
 * Multiple kind of code complication was observed in CNS audit.
+* Utilities [from Indigo](https://github.com/IndigoProtocol/indigo-smart-contracts/blob/main/src/Indigo/Utils/Spooky/Helpers.hs)
+
 
 ### Single script safety and liveliness
 
@@ -172,6 +179,9 @@ Our script stages abstraction cover all those kind of problems.
 
 ## Logic duplication and spec subtleness
 
+There is a bunch of very common tasks shared by multiple DApps,
+which could be tackled generically in our framework.
+
 ### Human-readable specification
 
 Designing, understanding and auditing any non-trivial DApp
@@ -195,31 +205,46 @@ is much less obvious to implement,
 and out of scope of current Catalyst project,
 but it is very much possible feature as well.
 
-### On-/Off-chain and spec code duplication
+Examples of this done by hand:
 
-@todo #3: Add more off-chain code duplication examples from existing PABs.
-    Include problems with querying coin-selection, tests, retrying and errors.
+* [State graph for Agora](https://github.com/Liqwid-Labs/agora/blob/staging/docs/diagrams/ProposalStateMachine.png)
+
+### Computer readable spec and hashes
+
+Script hashes and sizes summary is essential
+for DApp users and testers to check on-chain script are matching.
+We provide generic implementation showing all DApp hashes via CIP.
+
+### Indexing and querying code duplication
+
+Our framework simplifies generation of common queries
+and custom indexing.
+
+Querying of current script state is required for almost any DApp,
+and they are usually implemented with bunch of boilerplate.
+
+Examples of boilerplate:
+
+* [Querying available vestings](https://github.com/geniusyield/atlas-examples/blob/main/vesting/offchain/Vesting/Api.hs#L27)
+
+Customized transaction indexing is important for providing
+data to almost any kind of custom web-backend.
+Customized indexing may reduce storage space or SaaS dependence.
+
+Indexing transactions and parsing it back to state-machine transition
+is required for delegated architectures, including many DApps and Hydra L2.
+
+Examples of boilerplate:
+
+* https://github.com/MELD-labs/cardano-defi-public/tree/eacaa527823031105eba1730f730e1b32f1470bc/lending-index/src/Lending/Index
 
 ### Correct off-chain Tx construction logic
 
 A lot of on-chain problems, like timing and coin change issues
 have their counterpart on Tx submission side.
 
-### Common backend features
-
-There is a list of common tasks shared by multiple backends,
-which could be tackled generically in our framework.
-
-* Parsing transaction back to state-machine transition
-  is required for delegated architectures,
-  including almost any DApp on Hydra L2.
-* Customized transaction indexing is important for providing
-  data to almost any kind of custom web-backend.
-  Also usage of customized indexing may reduce storage space or SaaS dependence for DApp dependent on old transactions being recorded.
-  Our framework simplifies generation of custom indexing solution,
-  based on transition parsing feature.
-* Script hashes and sizes summary is essential
-  for DApp users and testers to check on-chain script are matching.
+@todo #3: Add more off-chain code duplication examples from existing PABs.
+  Include problems with coin-selection, tests, retrying and errors.
 
 # Existing solutions
 
@@ -364,12 +389,17 @@ Any kind of on-chain PL can only cover goals
 As far as we aware, none of them are trying
 to solve other goals.
 
-Known examples:
-
-* Aiken
-* Helios
-* https://github.com/OpShin/opshin
-* PureScript Backend project
+Known examples of PLs:
+
+* [Marlowe](https://github.com/input-output-hk/marlowe-plutus)
+  - Finance contracts DSL
+* [Aiken](https://aiken-lang.org/)
+  - OnChain PL with IDE support and testing framework
+* [Helios](https://www.hyperion-bt.org/helios-book/api/index.html)
+  - Onchain PL and frontend Tx sending library
+* [OpShin](https://github.com/OpShin/opshin)
+  - Onchain PL
+* Purs - PureScript Onchain PL
 
 Same stands for any known kind of frontend framework: