Merge branch 'main' into SCP-3073-emulated-ledger

.github/workflows/test.yml

@@ -20,3 +20,17 @@ jobs:
       - uses: actions/checkout@v2.3.4
       - uses: nixbuild/nix-quick-install-action@v9
       - run: nix-build -A tests.nixpkgsFmt -A tests.purty -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:
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v2.3.4
+      - uses: nixbuild/nix-quick-install-action@v9
+      - run: |
+          nix --extra-experimental-features 'nix-command flakes' flake lock --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/"
+          nix-shell --command "cd plutus-playground-client && (update-client-deps || update-client-deps)" --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/" # Double-call to work around bug in spago2nix on first fetch
+          # Disabled until we can find a way to run it only for Linux
+          # nix-shell --command "updateMaterialized" --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/"
+          git diff --exit-code

cabal.project

@@ -10,6 +10,7 @@ packages: doc
           plutus-ledger
           plutus-ledger-constraints
           plutus-pab
+          plutus-pab-executables
           plutus-playground-server
           plutus-use-cases
           quickcheck-dynamic

default.nix

@@ -33,7 +33,7 @@ rec {
 
   inherit (plutus-apps) web-ghc;
 
-  inherit (haskell.packages.plutus-pab.components.exes)
+  inherit (haskell.packages.plutus-pab-executables.components.exes)
     plutus-pab-examples
     plutus-uniswap;
 
@@ -51,12 +51,12 @@ rec {
   };
 
   # TODO: Fails for now because of webpack can't include `nami-wallet` lib in it's bundle.
-  # To reproduce the error, run `npm run build:webpack:prod` in `plutus-pab/demo/pab-nami/client`
+  # To reproduce the error, run `npm run build:webpack:prod` in `plutus-pab-executables/demo/pab-nami/client`
   pab-nami-demo = pkgs.recurseIntoAttrs rec {
-    inherit (pkgs.callPackage ./plutus-pab/demo/pab-nami/client {
+    inherit (pkgs.callPackage ./plutus-pab-executables/demo/pab-nami/client {
       inherit pkgs haskell webCommon;
       inherit (plutus-apps.lib) buildPursPackage buildNodeModules filterNpm gitignore-nix;
-    }) client pab-setup-invoker pab-nami-demo-invoker generate-purescript generated-purescript start-backend;
+    }) client pab-setup-invoker pab-nami-demo-invoker pab-nami-demo-generator generate-purescript generated-purescript start-backend;
   };
 
   plutus-use-cases = pkgs.recurseIntoAttrs (pkgs.callPackage ./plutus-use-cases {

doc/plutus/explanations/pab.rst

@@ -52,7 +52,7 @@ The PAB subscribes to ledger state updates from the node, using a socket protoco
 Wallet
 ~~~~~~
 
-A Cardano wallet is required for balancing and signing transactions.
+A Cardano wallet is required for balancing and signing transactions (and optionnaly submitting transactions).
 Balancing means taking a partial transaction and adding inputs and outputs to make the transaction valid.
 
 Take :ref:`Marlowe<introducing-marlowe>` as an example.
@@ -63,6 +63,14 @@ When the Marlowe contract has finished, funds are transferred back to the user's
 The PAB sends another partial transaction, this time with a single script input and no outputs.
 The wallet then adds an output at one of its own addresses to receive the funds.
 
+There are multiple ways to setup a wallet:
+
+1. Host a cardano wallet backend instance (WBE) using `cardano-wallet <https://github.com/input-output-hk/cardano-wallet>`_
+2. Setup a desktop wallet application (ex. `Daedalus <https://daedaluswallet.io/>`_)
+3. Setup a browser wallet application (ex. `Nami <https://namiwallet.io>`_, `Yoroi <https://yoroi-wallet.com>`_, etc.)
+
+These different wallet setups each imply a different use-case of the PAB.
+
 Deployment Scenarios
 --------------------
 
@@ -76,12 +84,70 @@ Hosted
 In the “Hosted PAB” scenario, the dApp provider / developer hosts an instance of the PAB alongside the :ref:`chain index<pab_chain_index>` and an Alonzo node.
 The off-chain code of the Plutus app is run on the dApp provider’s infrastructure.
 
-.. figure:: ./hosted-pab.png
+In the following sections, we illustrate the ways a hosted PAB can be used with the different type of wallets.
+
+WBE (Supported)
+^^^^^^^^^^^^^^^
+
+In this wallet scenario, the dApp provider /developer also hosts an instance of the WBE, which handles the wallets for each user.
+The WBE handles balancing, signing and submitting transaction requests from the PAB.
+
+.. figure:: ./hosted-pab-wbe.png
+
+    The hosted deployment scenario for the PAB with the WBE
 
-    The hosted deployment scenario for the PAB.
+This is currently used for testing purposes and shouldn't be used in a production setting, because we wallets are normally controlled by the users themselves.
 
-Coin selection and transaction signing (in short: anything that deals with the user’s money) happens on the user’s machine.
-The PAB produces a link (URI) for each partial transaction that needs to be balanced and signed.
+A simple demo of this scenario is available here: `<https://github.com/input-output-hk/plutus-apps/tree/main/plutus-pab/test-node>`_.
+
+Desktop wallet (Not yet supported)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this wallet scenario, the user has setup a desktop wallet (light or full node) such as Daedalus.
+Transaction balancing (coin selection) and transaction signing (in short: anything that deals with the user’s money) happens on the user’s machine.
+The PAB produces a link (URI) for each partial transaction that needs to be balanced, signed and submitted.
 When the user clicks the link, the user's operating system opens the wallet that is registered to handle the link schema.
-This scheme is not restricted to Daedalus, or even to full wallets.
+This scheme is not restricted to Daedalus, or even to full node wallets.
 Any wallet that implements a handler for the link schema can be used to balance, sign and submit Plutus transactions.
+
+.. figure:: ./hosted-pab-cardano-wallet.png
+
+    The hosted deployment scenario for the PAB communicating with a desktop wallet.
+
+Browser wallet (In progress)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this wallet scenario, the user has setup a browser wallet such as Nami or Yoroi.
+The PAB updates it's contract instance status endpoint for each partial transaction that needs to be balanced, signed and submitted.
+Transaction signing happens on the user's machine.
+However, transaction balancing (coin selection) is handled by the PAB as it is not currently possible to balance transaction that contain script inputs in the browser (i.e. browser wallets can't balance transactions until it is possible to execute Plutus script in the browser).
+Therefore, browser wallets will need to call a PAB helper endpoint which can balance the transaction using funds from the user's browser wallet.
+
+.. figure:: ./hosted-pab-browser-wallet.png
+
+    The hosted deployment scenario for the PAB communicating with a browser wallet.
+
+A simple demo of this scenario is available here: `<https://github.com/input-output-hk/plutus-apps/tree/main/plutus-pab-executables/demo/pab-nami>`_.
+This demo is a work in progress.
+
+In-browser
+~~~~~~~~~~
+
+In the “In-browser PAB” scenario, the dApp provider / developer hosts an instance of the :ref:`chain index<pab_chain_index>` and an Alonzo node.
+The dApp users work with a browser interface which uses a light version of the PAB.
+
+Similary to the hosted PAB scenario, we illustrate the ways it can be used the different type of wallets.
+
+Desktop wallet (Not yet supported)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: ./in-browser-pab-cardano-wallet.png
+
+    The in-browser PAB communicating with a desktop wallet.
+
+Browser wallet (Not yet supported)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: ./in-browser-pab-browser-wallet.png
+
+    The in-browser PAB communicating with a browser wallet.

doc/reference/examples.rst

@@ -3,7 +3,7 @@
 Examples
 ========
 
-Full examples of Plutus Applications can be found in the ``plutus`` `repository <https://github.com/input-output-hk/plutus/tree/master/plutus-use-cases>`_.
+Full examples of Plutus Applications can be found in the ``plutus-apps`` `repository <https://github.com/input-output-hk/plutus-apps/tree/main/plutus-use-cases>`_.
 The source code can be found in the ``src`` and the tests in the ``test`` folder.
 
 The examples are a mixture of simple examples and more complex ones, including:
@@ -14,4 +14,4 @@ The examples are a mixture of simple examples and more complex ones, including:
 - A uniswap clone
 
 .. important::
-  Make sure to look at the same version of the `plutus` repository as you are using, to ensure that the examples work.
+  Make sure to look at the same version of the `plutus-apps` repository as you are using, to ensure that the examples work.

flake.nix

@@ -42,7 +42,7 @@
     };
     haskell-language-server = {
       # Pinned to a release
-      url = "github:haskell/haskell-language-server?ref=1.3.0";
+      url = "github:haskell/haskell-language-server?ref=1.5.1";
       flake = false;
     };
     iohk-nix = {

nix/pkgs/haskell/haskell.nix

@@ -83,6 +83,7 @@ let
           plutus-ledger.package.buildable = false;
           plutus-ledger-constraints.package.buildable = false;
           plutus-pab.package.buildable = false;
+          plutus-pab-executables.package.buildable = false;
           plutus-playground-server.package.buildable = false; # Would also require libpq
           plutus-tx-plugin.package.buildable = false;
           plutus-use-cases.package.buildable = false;
@@ -140,7 +141,7 @@ let
           # Relies on cabal-doctest, just turn it off in the Nix build
           prettyprinter-configurable.components.tests.prettyprinter-configurable-doctest.buildable = lib.mkForce false;
 
-          plutus-pab.components.tests.plutus-pab-test-full-long-running = {
+          plutus-pab-executables.components.tests.plutus-pab-test-full-long-running = {
             platforms = lib.platforms.linux;
           };
 
@@ -156,6 +157,7 @@ let
           plutus-ledger-constraints.ghcOptions = [ "-Werror" ];
           plutus-playground-server.ghcOptions = [ "-Werror" ];
           plutus-pab.ghcOptions = [ "-Werror" ];
+          plutus-pab-executables.ghcOptions = [ "-Werror" ];
           plutus-doc.ghcOptions = [ "-Werror" ];
           plutus-use-cases.ghcOptions = [ "-Werror" ];
 

nix/pkgs/haskell/hls-darwin.sha

@@ -1 +1 @@
-00r15hn2q609j59ajgn3bdq6vlzh426sjhb0war8wj5dbz5z5zis
+0jjn7a2infis7mfjda7zpz2jwhgc7y8qwn54a2wqn08dk76v9kzm

nix/pkgs/haskell/hls-linux.sha

@@ -1 +1 @@
-1gk5ispzwn3yv3z9583xg86w0ih3j7ac65bnaxjn6gb1lr530v6y
+08g0pbrqzw55l8cam8qq4v0q0gyrqv84z5y1zgzynkg9i709ypwy