Merge branch 'main' into kll/reactivate-goldenpir-tests

.buildkite/pipeline.yml

@@ -1,6 +1,7 @@
 steps:
   - label: ':shipit: deploy devcontainer image for plutus-starter'
-    branches: "plutus-starter-devcontainer/v*"
+    # For example, "v0.1.0" will match, but not "plutus-starter-devcontainer/v0.1.0" or "v0.1.0-rc1"
+    branches: "v*.*.* !v*-*"
     command:
       - "./.buildkite/plutus-starter-devcontainer-push.sh"
     concurrency: 1

.github/workflows/plutus-playground-e2e-tests.yml

@@ -30,13 +30,13 @@ jobs:
       run: nix-build -A plutus-playground.client -A plutus-playground.server
 
     - name: Run Plutus Playground
-      working-directory: ./plutus-playground-client
       env:
         CLIENT_PORT: 8009
       run: |
-        nix-shell --run 'plutus-playground-server' ../shell.nix &
-        nix-shell --run 'npm start' ../shell.nix &
-        while ! echo exit | nc localhost $CLIENT_PORT; do echo "Waiting for playground client on $CLIENT_PORT" && sleep 10; done
+        nix-shell --run 'plutus-playground-server' shell.nix &
+        while ! [ -d plutus-playground-client/generated ]; do echo "Waiting for server to generate purescript sources" && sleep 10; done
+        nix-shell --run '(cd plutus-playground-client && npm start)' shell.nix &
+        while ! echo exit | nc localhost 8009; do echo "Waiting for playground client on 8009" && sleep 10; done
   
     - name: Setup NodeJs
       uses: actions/setup-node@v3

.github/workflows/test.yml

@@ -18,8 +18,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - uses: nixbuild/nix-quick-install-action@v16
-      - run: nix-build -A tests.nixpkgsFmt -A tests.purs-tidy -A tests.shellcheck -A tests.stylishHaskell -A tests.generated --arg supportedSystems '[ builtins.currentSystem ]' --restrict-eval -I . --allowed-uris 'https://github.com/NixOS/nixpkgs https://github.com/input-output-hk https://github.com/NixOS/nixpkgs-channels' --option trusted-public-keys "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=" --option substituters "https://hydra.iohk.io https://iohk.cachix.org https://cache.nixos.org/"
+      - uses: nixbuild/nix-quick-install-action@v15
+      - run: nix-build -A tests.nixpkgsFmt -A tests.cabalFmt -A tests.purs-tidy -A tests.pngOptimization -A tests.shellcheck -A tests.stylishHaskell --arg supportedSystems '[ builtins.currentSystem ]' --restrict-eval -I . --allowed-uris 'https://github.com/NixOS/nixpkgs https://github.com/input-output-hk https://github.com/NixOS/nixpkgs-channels' --option trusted-public-keys "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=" --option substituters "https://hydra.iohk.io https://iohk.cachix.org https://cache.nixos.org/"
   check-for-updates:
     strategy:
       matrix:

.gitignore

@@ -76,6 +76,8 @@ pkgs/.stack
 **/.spago/
 **/.spago2nix/
 **/.psa-stash
+plutus-playground-client/generated
+plutus-pab-executables/demo/pab-nami/client/generated
 
 # Backend config files
 marlowe-playground-server/playground.yaml

.stylish-haskell.yaml

@@ -28,4 +28,6 @@ language_extensions:
   - PackageImports
   - QuasiQuotes
   - ScopedTypeVariables
-  - TemplateHaskell
+  - TemplateHaskell
+  - TypeApplications
+  - ImportQualifiedPost

CONTRIBUTING.adoc

@@ -432,6 +432,8 @@ The documentation site is built on ReadTheDocs.
 It will build a preview for each PR which is linked from the PR status.
 It's useful to take a look if you're changing any of the documentation.
 
+Run `build-and-serve-docs` in nix-shell to host a local instance at http://0.0.0.0:8002/. Haddock is at http://0.0.0.0:8002/haddock.
+
 ==== Github Actions
 
 These perform some of the same checks as Hydra, but Github Actions is often more available, so they return faster and act as a "smoke check".

README.adoc

@@ -65,14 +65,20 @@ The core `plutus-apps` packages are versioned as follows:
 
 * Package versioning follows the https://pvp.haskell.org/[PVP] on a best-effort basis (i.e. we will generally try to but we won't guarantee it).
 ** The first-major-version component indicates the "era" which for our purposes means which major version of the *Cardano node* the tools are compatible with.
+*** Alonzo era: `v0.x.x`
+*** Babbage era: `v1.x.x`
 ** The second-major-version component is used for releases which are major versions according to the PVP, but which are still compatible with the current "era".
 ** The minor-version and below are used as normal.
 * Packages which are used downstream should all have the same version.
 * Other packages which are not used downstream (e.g. `plutus-playground-server`, `plutus-playground-client`, `quickcheck-dynamic`, etc.) can remain unversioned.
 
 In principle we could just have a single major version, but using two makes it easier to avoid mistakes and clearly expresses the state of the repository.
 
-=== Branching
+=== Branching and tagging
+
+The following tagging rules are followed:
+
+* Version `X` is tagged as `vX`
 
 There are two protected branches in `plutus-apps`:
 
@@ -82,7 +88,7 @@ There are two protected branches in `plutus-apps`:
 ** The version of transitive dependencies (`plutus`, `cardano-ledger`, `ouroboros-network`, etc.) should be pinned to the ones from `cardano-node` (or better, `cardano-wallet`)
 ** Changes will be backported form `main` to `next-node`
 * `next-node` branch: should always target the next node release.
-** This branch will eventually be merged in `main` after the Cardano mainnet HF.
+** This branch will eventually be merged in `main` after the Cardano mainnet HF and deleted. Once the next HF is planned, it will be recreated and it will contain an upgraded `cardano-node` version.
 
 === Dependency update
 

bitte/static-site.nix

@@ -15,11 +15,11 @@ let
       ".jpg" => "image/jpeg",
       ".jpeg" => "image/jpeg",
       ".html" => "text/html",
-      ".js"           =>      "text/javascript",
-      ".svg"          =>      "image/svg+xml",
+      ".js" => "text/javascript",
+      ".svg" => "image/svg+xml",
     )
-    deflate.cache-dir   = "/tmp"
-    deflate.mimetypes    = ("text/plain", "text/html", "text/css")
+    deflate.cache-dir = "/tmp"
+    deflate.mimetypes = ("text/plain", "text/html", "text/css")
     server.upload-dirs = ("/tmp")
   '';
 in

cabal.project

@@ -8,6 +8,7 @@ packages: doc
           plutus-chain-index-core
           plutus-contract
           plutus-example
+          plutus-hysterical-screams 
           plutus-contract-certification
           plutus-ledger
           plutus-ledger-constraints
@@ -18,7 +19,6 @@ packages: doc
           plutus-tx-constraints
           plutus-use-cases
           plutus-streaming
-          quickcheck-dynamic
           web-ghc
 
 -- We never, ever, want this.
@@ -301,8 +301,8 @@ source-repository-package
   location: https://github.com/input-output-hk/Win32-network
   tag: 3825d3abf75f83f406c1f7161883c438dac7277d
 
--- Temporary indexing
+
 source-repository-package
   type: git
-  location: https://github.com/raduom/hysterical-screams
-  tag: 4c523469e9efd3f0d10d17da3304923b7b0e0674
+  location: https://github.com/input-output-hk/quickcheck-dynamic
+  tag: c272906361471d684440f76c297e29ab760f6a1e

default.nix

@@ -43,7 +43,7 @@ rec {
       inherit (plutus-apps) purs-tidy;
       inherit (plutus-apps.lib) buildPursPackage buildNodeModules filterNpm gitignore-nix;
       inherit haskell webCommon;
-    }) client server start-backend generate-purescript generated-purescript;
+    }) client server start-backend generate-purescript;
   };
 
   # TODO: Fails for now because of webpack can't include `nami-wallet` lib in it's bundle.
@@ -53,7 +53,7 @@ rec {
       inherit (plutus-apps) purs-tidy;
       inherit pkgs haskell webCommon;
       inherit (plutus-apps.lib) buildPursPackage buildNodeModules filterNpm gitignore-nix;
-    }) client pab-setup-invoker pab-nami-demo-invoker pab-nami-demo-generator generate-purescript generated-purescript start-backend;
+    }) client pab-setup-invoker pab-nami-demo-invoker pab-nami-demo-generator start-backend;
   };
 
   plutus-use-cases = pkgs.recurseIntoAttrs (pkgs.callPackage ./plutus-use-cases {
@@ -64,14 +64,16 @@ rec {
 
   plutus-chain-index = plutus-apps.haskell.packages.plutus-chain-index.components.exes.plutus-chain-index;
 
+  marconi = plutus-apps.haskell.packages.plutus-chain-index.components.exes.marconi;
+
+  create-script-context = plutus-apps.haskell.packages.plutus-example.components.exes.create-script-context;
+
   tests = import ./nix/tests/default.nix {
     inherit pkgs docs;
     inherit (plutus-apps.lib) gitignore-nix;
     inherit (plutus-apps) fixStylishHaskell fix-purs-tidy fixPngOptimization fixCabalFmt;
     inherit plutus-playground web-ghc;
     src = ./.;
-    play-generated = plutus-playground.generated-purescript;
-    nami-generated = pab-nami-demo.generated-purescript;
   };
 
   docs = import ./nix/docs.nix { inherit pkgs plutus-apps; };

doc/README.md

@@ -1,17 +1,29 @@
-# Plutus and Marlowe documentation site
+# Plutus documentation site
 
-This is a sphinx site. You can build it with sphinx directly (assuming you're in a `nix-shell`):
+This is a sphinx site. 
+Assuming you're in a `nix-shell`, from the top-level, you can either build the site directly:
 
 ```
-$ cd doc
-$ sphinx-build -j 4 -n . _build # Open '_build/index.html' in your browser
+sphinx-build -j 4 -n doc doc/_build 
 ```
 
-Or you can build it with Nix at the top level, which will also build the Haddock for the project and link it in:
+And then open `doc/_build/index.html` in your browser.
+
+
+Or you can get yourself a development server with live reload on `http://127.0.0.1:8000`:
+
+```
+sphinx-autobuild -j 4 -n doc doc/_build 
+```
+
+Or you can use Nix which will also build the Haddock for the project and link it in:
 
 ```
-$ nix build -f default.nix docs.site
+nix build -f default.nix docs.site
 ```
 
+Or you can run `build-and-serve-docs` in nix-shell to host a local instance of ReadTheDocs at http://0.0.0.0:8002/. Haddock is at http://0.0.0.0:8002/haddock.
+
 The doc site from main is built automatically and hosted [here](https://plutus-apps.readthedocs.io/en/latest).
+
 Additionally, the site is built for all PRs, and a link to a preview can be found in the PR statuses.

doc/adr/0001-record-architecture-decisions.rst

@@ -3,7 +3,7 @@ ADR 1: Record architectural decisions
 
 Date: 2022-06-08
 
-Author(s)
+Authors
 ---------
 
 koslambrou <[email protected]>
@@ -83,6 +83,15 @@ What follows is the ADR format (adapted from the book).
 |                      | For example, "ADR 1: Deployment on Ruby on Rails 3.0.10"                  |
 |                      | or "ADR 9: LDAP for Multitenant Integration"                              |
 +----------------------+---------------------------------------------------------------------------+
+| Authors              | List each author's name and email.                                        |
++----------------------+---------------------------------------------------------------------------+
+| Status               | State the status of the decision, such as "draft" if the decision is      |
+|                      | still being written, as "proposed" if the project stakeholders haven't    |
+|                      | agreed with it yet, "accepted" once it is agreed. If a later ADR changes  |
+|                      | or reverses a decision, it may be marked as "deprecated" or "superseded"  |
+|                      | with a reference to its replacement. (This is not the status of           |
+|                      | implementing the decision.)                                               |
++----------------------+---------------------------------------------------------------------------+
 | Issue (or context)   | This section describes the architectural design issue being addressed.    |
 |                      | This description should leave no questions as to why this issue needs to  |
 |                      | be addressed now. The language in this section is value-neutral. It is    |
@@ -92,13 +101,6 @@ What follows is the ADR format (adapted from the book).
 |                      | positions that the architect could have taken. It is stated in full       |
 |                      | sentences, with active voice. "We will …"                                 |
 +----------------------+---------------------------------------------------------------------------+
-| Status               | State the status of the decision, such as "draft" if the decision is      |
-|                      | still being written, as "proposed" if the project stakeholders haven't    |
-|                      | agreed with it yet, "accepted" once it is agreed. If a later ADR changes  |
-|                      | or reverses a decision, it may be marked as "deprecated" or "superseded"  |
-|                      | with a reference to its replacement. (This is not the status of           |
-|                      | implementing the decision.)                                               |
-+----------------------+---------------------------------------------------------------------------+
 | Tags                 | Add one or more tags to the decision. Useful for organizing the set of    |
 |                      | decision.                                                                 |
 +----------------------+---------------------------------------------------------------------------+

doc/adr/0002-repository-standardization.rst

@@ -0,0 +1,120 @@
+.. _repository_standardization:
+
+ADR 2: Repository Standardization
+=======================================
+
+Date: 2022-07-06
+
+Authors
+---------
+
+Lorenzo Calegari <[email protected]>
+
+Status
+------
+
+Draft
+
+Context
+-------
+
+IOG is undertaking a company-wide effort to restructure and standardize its 
+repositories, favoring mono-repos and enforcing shared GitOps and DevOps 
+processes. Parallel to this, a new CI infrastructure is being developed.
+
+Examples of this are:
+
+* `input-output-hk/cardano-world <https://github.com/input-output-hk/cardano-world>`_
+* `input-output-hk/ci-world <https://github.com/input-output-hk/ci-world>`_
+* `input-output-hk/atala-world <https://github.com/input-output-hk/atala-world>`_
+
+This initiative appears to be championed by the SRE team who are the creators of 
+`divnix/std <https://github.com/divnix/std>`_. Indeed `std` is at the heart of 
+the standardization dream.
+
+Decision
+--------
+
+* Standardization of the repositories has been deemed a worthwhile endeavour, 
+  though of very low priority. 
+* Phase 1 of the standardization process will be carried out in parallel with 
+  :ref:`Move Marconi to a separate repository <marconi_monorepo>`.
+  A separate repository will be created for Marconi, and from the very beginning 
+  it will use `std`. This way the benefits, limitations and integration costs of 
+  `std` can be experienced and measured, and an informed, definitive decision on 
+  standardizing `plutus-core` and `plutus-apps` themselves can be made. 
+
+Argument
+------------
+
+In short, `std` aims to answer the one critical question that pops in the mind 
+of newcomers and veterans alike: 
+
+*What can I do with this repository?*
+
+In practice, `std` is flake-based nix library code that provides a 
+strongly-but-sensibly-opinionated top-level interface for structuring all your 
+nix code.
+
+This is wonderful news for the owner of the repository's nix code, but what
+about every other stakeholder? Especially developers who don't care/know about 
+nix? 
+
+Contributors of a standardized codebase will be gifted with a TUI to discover 
+and interact with the repository, which is probably something that is long 
+overdue as an industry-level best-practice.
+
+Who wouldn't want to clone a repository, type `std` and be presented with a TUI 
+that gives you an interactive tour of the repository's artifacts, together with 
+a list of all possible DevOps and GitOps actions (build, test, develop, run, 
+deploy, benchmark, publish, package, monitor, ...) in addition to any other 
+action that you may define. 
+
+And for power users and automators, there is an equivalent CLI to the TUI. 
+This makes `README` files obsolete to an extent. 
+A TUI/CLI combo represents the best conceivable solution in terms of user 
+experience (only a GUI could top that perhaps).
+
+In conclusion, the advantages of standardizing the repositories are:
+
+* Enforce a shared mental model for internal and external teams to effortlessly 
+  reason about the codebase.
+* Provide a TUI/CLI to more easily discover, interact with, and contribute to 
+  the repository, with the goal to provide a superior user experience to all 
+  stakeholders.
+* Refactor all existing Nix code into a supposedly far better structure. 
+  `std` seems to solve the "import problem" by automatically parsing the 
+  directory structure and threading all derivations into a globally accessible 
+  top-level scope, drastically reducing the average length of paths in the 
+  dependency graph, both at the file level and at the term/variable level. 
+  This all translates into cleaner, more maintainable code.
+
+Implications
+------------
+
+The plutus repositories now exhibit a large amount of duplicated nix 
+(and configuration) code, as a result of the split into `plutus-core`
+and `plutus-apps`.
+
+While introducing `std` will not in itself help reduce duplication, the 
+refactoring process will involve identifying and isolating shared components 
+that can be later packaged and separated into library code. 
+
+The goal is to standardize both repositories, by introducing `std` and 
+refactoring all existing nix code accordingly. 
+
+The SRE team has also created several other satellite repositories containing 
+reusable nix code to support this process, though it is unclear at this stage 
+whether these are relevant to standardizing `plutus-core` and `plutus-apps`.
+
+Such repositories include:
+
+* `nixagii <https://github.com/input-output-hk/nixagii>`_
+* `devshell-capsules <https://github.com/input-output-hk/devshell-capsules>`_
+* `kladoi <https://github.com/input-output-hk/kladoi>`_
+
+
+The standardization process would follow the `4 Layers SRE Mental Model <https://sre-manual.infra.aws.iohkdev.io/mental-model.html>`_, 
+which begins by introducing `std` in Layer 1 (binary packaging).
+Layers 2-3-4 (which is mostly DevOps) will be postponed to a later date, once 
+the migration to the new CI systems has been officially approved and initiated.