Merge pull request #454 from input-output-hk/update-next-node-branch

Update next node branch with main branch

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

@@ -13,7 +13,7 @@ jobs:
       uses: actions/checkout@v3
 
     - name: Setup Haskell
-      uses: haskell/actions/setup@v1
+      uses: haskell/actions/setup@v2
       with:
         ghc-version: '8.10.4'
         cabal-version: '3.2.0.0'

.github/workflows/test.yml

@@ -9,16 +9,16 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - uses: nixbuild/nix-quick-install-action@v12
-      - run: nix-instantiate release.nix --arg checkMaterialization true --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/" --show-trace
+      - uses: nixbuild/nix-quick-install-action@v13
+      - run: nix-instantiate release.nix --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/" --show-trace
   nix-tests:
     strategy:
       matrix:
         os: [ubuntu-latest]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - uses: nixbuild/nix-quick-install-action@v12
+      - uses: nixbuild/nix-quick-install-action@v13
       - 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/"
   check-for-updates:
     strategy:
@@ -27,7 +27,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - uses: nixbuild/nix-quick-install-action@v12
+      - uses: nixbuild/nix-quick-install-action@v13
       - run: |
           nix --extra-experimental-features 'nix-command flakes' --extra-experimental-features 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 --extra-experimental-features 'nix-command flakes' --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

CONTRIBUTING.adoc

@@ -32,7 +32,6 @@ The shell comes with some tools for fixing various simple problems that the CI w
 - `fix-stylish-haskell` will re-format all the Haskell sources correctly.
 - `fix-purs-tidy` will re-format all the Purescript sources correctly.
 - `fix-png-optimization` will optimize all PNGs in the repository.
-- `updateMaterialized` will update the materialized Nix files (see xref:update-generated[later]).
 
 If you're not using `nix-shell` all the time and you want to run one of these, you can use `nix-shell --run`.
 
@@ -108,28 +107,13 @@ NOTE: you must run your editor from the nix shell, and not from, say, an
 application launcher like spotlight or dmenu for your editor to find it in
 its PATH.
 
-[[update-generated]]
-=== How to update the generated Haskell package set
-
-Some of the Nix code that builds all the Haskell packages and their dependencies is generated automatically.
-However, to avoid doing too much work all the time, we have checked the generated output in.
-
-IMPORTANT: These files needs to be regenerated if you change any dependencies in cabal files.
-But the CI will tell you if you've failed to do so.
-
-You can regenerate the files by running `updateMaterialized` (provided by `nix-shell`) from the repository root.
-
-This will also update the `plan-256` shas for the extra Haskell tools, if you have a problem iwth that.
-
 === How to add a new Haskell package
 
 You need to do a few things when adding a new package, in the following order:
 
 . Add the cabal file for the new package.
 . Add the package to link:cabal.project[`cabal.project`].
 . Add the package to link:stack.yaml[`stack.yaml`].
-. Update the xref:update-generated[package set].
-. Update the `xref:update-hie[hie-*.yaml` files].
 . Check that you can run `nix build -f default.nix plutus.haskell.projectPackages.<package name>` successfully.
 
 [[update-haskell-pins]]
@@ -140,7 +124,6 @@ We have pinned versions of some Haskell packages specified via the usual `source
 These can be managed normally, but ensure that:
 
 * The specifications remain in sync between `cabal.project` and `stack.yaml`.
-* You update the xref:update-generated[package set].
 * If it is an `source-repository-package`/`extra-dep` from Git, you update the `sha256` mapping in `nix/haskell.nix`.
 For the moment you have to do this by hand, using the following command to get the sha: `nix-prefetch-git --quiet <repo-url> <rev> | jq .sha256`, or by just getting it wrong and trying to build it, in which case Nix will give you the right value.
 * For certain dependencies like `plutus`, please run `nix flake lock --update-input <input-name>` to update `flake.lock`. A wrong-hash error on a `nix build` is a common hint.
@@ -175,8 +158,6 @@ The set of index states which it knows about is controlled by `hackage.nix`, whi
 This therefore needs to be newer than the index state.
 You can update it xref:update-nix-pins[with the Nix flake commands].
 
-You will need to update the xref:update-generated[package set] after this to reflect the new build plan that Cabal will pick.
-
 === How to work with a local copy of source dependencies
 
 Sometimes you may want to make a change that spans both `plutus-apps` *and* some of its dependencies (most commonly, the packages in `plutus`).

README.adoc

@@ -50,6 +50,78 @@ The generated Haskell API documentation (haddocks) are here:
 
 - https://hydra.iohk.io/job/Cardano/plutus/linux.docs.plutus-report/latest/download-by-type/doc-pdf/plutus[Plutus Technical Report] (draft)
 
+== Versioning and releases
+
+https://pvp.haskell.org/[PVP] reminder:
+
+* _Two_ major-version components, A.B
+** In this doc: “first-major-version”, “second-major-version”
+* _One_ minor-version component C
+* Any number of (meaningless but higher) patch-version components
+
+=== Versioning
+
+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.
+** 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
+
+There are two protected branches in `plutus-apps`:
+
+* `main` branch
+** Most development should be done in this branch
+** Should always target a stable version of `cardano-node` which is compatible with the current Cardano mainnet.
+** 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.
+
+=== Dependency update
+
+The dependency update policy is dependent on the protected branch.
+
+For `cardano-node`, we define major-version-bound the range of versions which are compatible with a specific era.
+For example, for the Alonzo era, that would be `>= 1.29 && < 1.35`. For the Vasil era, that would be `>= 1.35 && < 1.36`.
+
+Independently of the protected branch:
+
+* It should always use the same first-major-version of `plutus` as the one used by the `plutus` dependency of `cardano-node`
+* It should always be safe to upgrade to a new second-major-version of `plutus`: at worst this will lead to some code breakage.
+* It should, unless specified otherwise, use the same version for transitive dependencies (`cardano-ledger`, `ouroboros-network`, etc.) with `cardano-node`
+* It should pin the major version of `cardano-node` for all packages
+* It should pin the first and second-major version of `plutus` for all packages
+
+`main` branch:
+
+* It should not update `cardano-node` to a new major-version. In other words, it should use a `cardano-node` version which is compatible with the current Cardano mainnet
+* It should use a `cardano-wallet` version which is compatible with the current `cardano-node` version
+
+`next-node` branch:
+
+* It may update the `cardano-node` to a new major-version. In other words, it may use a `cardano-node` version which is incompatible with the current Cardano mainnet
+* It may use a `cardano-wallet` version which is incompatible with the current `cardano-node` version
+
+=== Version ranges
+
+Packages which depend on `plutus-apps` packages should use version ranges to control which version of those packages they build against.
+
+* Packages in `plutus-apps` which are used downstream should pin the major-version of each other (e.g. `plutus-pab-1.0.1` should depend on `plutus-contract ^>= 1.0`).
+* Downstream packages should pin at least the first-major-version of `plutus-apps` packages.
+** Upgrading to a new second-major-version should always be safe for working on the current mainnet, with at most code breakage (following the PVP). Users may of course want to pin this version as well to avoid such breakage.
+* Downstream packages pulling in `plutus-apps` packages via `source-repository-package` stanzas should always take tagged commits.
+
+=== Releases
+
+Currently there is no release process beyond bumping the package versions and making a tag/branch as appropriate.
+
 == Working with the project
 
 === How to submit an issue

ci.nix

@@ -3,8 +3,6 @@
   # on a machine with e.g. no way to build the Darwin IFDs you need!
   supportedSystems ? [ "x86_64-linux" "x86_64-darwin" ]
 , rootsOnly ? false
-  # We explicitly pass true here in the GitHub action but don't want to slow down hydra
-, checkMaterialization ? false
 , sourcesOverride ? { }
 , sources ? import ./nix/sources.nix { system = builtins.currentSystem; } // sourcesOverride
 , plutus-apps-commit ? { outPath = ./.; rev = "abcdef"; }
@@ -57,7 +55,7 @@ let
       # given a system ("x86_64-linux") return an attrset of derivations to build
       _select = _: system: crossSystem:
         let
-          packages = import ./default.nix { inherit system crossSystem checkMaterialization; };
+          packages = import ./default.nix { inherit system crossSystem; };
           pkgs = packages.pkgs;
           plutus-apps = packages.plutus-apps;
           # Map `crossSystem.config` to a name used in `lib.platforms`

default.nix

@@ -17,10 +17,7 @@
       stackage = sources.stackage-nix;
     };
   }
-, packages ? import ./nix { inherit system sources crossSystem config sourcesOverride haskellNix checkMaterialization enableHaskellProfiling; }
-  # Whether to check that the pinned shas for haskell.nix are correct. We want this to be
-  # false, generally, since it does more work, but we set it to true in the CI
-, checkMaterialization ? false
+, packages ? import ./nix { inherit system sources crossSystem config sourcesOverride haskellNix enableHaskellProfiling; }
   # Whether to build our Haskell packages (and their dependencies) with profiling enabled.
 , enableHaskellProfiling ? false
 }:

doc/plutus-doc.cabal

@@ -31,7 +31,7 @@ common lang
                         ImportQualifiedPost
     ghc-options: -Wall -Wnoncanonical-monad-instances
                  -Wincomplete-uni-patterns -Wincomplete-record-updates
-                 -Wredundant-constraints -Widentities
+                 -Wredundant-constraints -Widentities -Wmissing-import-lists
                  -- See Plutus Tx readme
                  -fobject-code -fno-ignore-interface-pragmas -fno-omit-interface-pragmas
 

doc/plutus/howtos/WriteScriptsTo.hs

@@ -6,14 +6,14 @@ import Data.Int (Int64)
 import Data.Monoid (Sum)
 import Ledger (ExBudget)
 import Plutus.Trace.Emulator (EmulatorConfig, EmulatorTrace)
-import Plutus.Trace.Emulator.Extract as Extract
+import Plutus.Trace.Emulator.Extract qualified as Extract
 
 -- BLOCK0
 {-| Run an emulator trace and write the applied scripts to a file in Flat format
     using the name as a prefix.
 -}
 writeScriptsTo
-    :: ScriptsConfig -- ^ Configuration
+    :: Extract.ScriptsConfig -- ^ Configuration
     -> String -- ^ Prefix to be used for file names
     -> EmulatorTrace a -- ^ Emulator trace to extract transactions from
     -> EmulatorConfig -- ^ Emulator config

doc/plutus/tutorials/BasicPlutusTx.hs

@@ -8,13 +8,13 @@ module BasicPlutusTx where
 
 import PlutusCore.Default qualified as PLC
 -- Main Plutus Tx module.
-import PlutusTx
+import PlutusTx qualified
 -- Additional support for lifting.
-import PlutusTx.Lift
+import PlutusTx.Lift (liftCode, makeLift)
 -- Builtin functions.
-import PlutusTx.Builtins
+import PlutusTx.Builtins qualified as Builtins
 -- The Plutus Tx Prelude, discussed further below.
-import PlutusTx.Prelude
+import PlutusTx.Prelude qualified as PlutusTx
 
 -- Setup for doctest examples.
 
@@ -26,15 +26,15 @@ import PlutusTx.Prelude
 -- >>> import Prettyprinter
 
 -- BLOCK2
-integerOne :: CompiledCode Integer
+integerOne :: PlutusTx.CompiledCode Builtins.Integer
 {- 'compile' turns the 'TExpQ Integer' into a
   'TExpQ (CompiledCode Integer)' and the splice
   inserts it into the program. -}
-integerOne = $$(compile
+integerOne = $$(PlutusTx.compile
     {- The quote has type 'TExpQ Integer'.
       We always use unbounded integers in Plutus Core, so we have to pin
       down this numeric literal to an ``Integer`` rather than an ``Int``. -}
-    [|| (1 :: Integer) ||])
+    [|| (1 :: Builtins.Integer) ||])
 
 {- |
 >>> pretty $ getPlc integerOne
@@ -43,8 +43,8 @@ integerOne = $$(compile
 )
 -}
 -- BLOCK3
-integerIdentity :: CompiledCode (Integer -> Integer)
-integerIdentity = $$(compile [|| \(x:: Integer) -> x ||])
+integerIdentity :: PlutusTx.CompiledCode (Builtins.Integer -> Builtins.Integer)
+integerIdentity = $$(PlutusTx.compile [|| \(x:: Builtins.Integer) -> x ||])
 
 {- |
 >>> pretty $ getPlc integerIdentity
@@ -60,25 +60,25 @@ integerIdentity = $$(compile [|| \(x:: Integer) -> x ||])
   you may be able to get away with omitting it, it is good practice to
   always include it. -}
 {-# INLINABLE plusOne #-}
-plusOne :: Integer -> Integer
+plusOne :: Builtins.Integer -> Builtins.Integer
 {- 'addInteger' comes from 'PlutusTx.Builtins', and is
   mapped to the builtin integer addition function in Plutus Core. -}
-plusOne x = x `addInteger` 1
+plusOne x = x `Builtins.addInteger` 1
 
 {-# INLINABLE myProgram #-}
-myProgram :: Integer
+myProgram :: Builtins.Integer
 myProgram =
     let
         -- Local functions do not need to be marked as 'INLINABLE'.
-        plusOneLocal :: Integer -> Integer
-        plusOneLocal x = x `addInteger` 1
+        plusOneLocal :: Builtins.Integer -> Builtins.Integer
+        plusOneLocal x = x `Builtins.addInteger` 1
 
         localTwo = plusOneLocal 1
         externalTwo = plusOne 1
-    in localTwo `addInteger` externalTwo
+    in localTwo `Builtins.addInteger` externalTwo
 
-functions :: CompiledCode Integer
-functions = $$(compile [|| myProgram ||])
+functions :: PlutusTx.CompiledCode Builtins.Integer
+functions = $$(PlutusTx.compile [|| myProgram ||])
 
 {- We’ve used the CK evaluator for Plutus Core to evaluate the program
   and check that the result was what we expected. -}
@@ -87,37 +87,37 @@ functions = $$(compile [|| myProgram ||])
 (con 4)
 -}
 -- BLOCK5
-matchMaybe :: CompiledCode (Maybe Integer -> Integer)
-matchMaybe = $$(compile [|| \(x:: Maybe Integer) -> case x of
-    Just n  -> n
-    Nothing -> 0
+matchMaybe :: PlutusTx.CompiledCode (PlutusTx.Maybe Builtins.Integer -> Builtins.Integer)
+matchMaybe = $$(PlutusTx.compile [|| \(x:: PlutusTx.Maybe Builtins.Integer) -> case x of
+    PlutusTx.Just n  -> n
+    PlutusTx.Nothing -> 0
   ||])
 -- BLOCK6
 -- | Either a specific end date, or "never".
-data EndDate = Fixed Integer | Never
+data EndDate = Fixed Builtins.Integer | Never
 
 -- | Check whether a given time is past the end date.
-pastEnd :: CompiledCode (EndDate -> Integer -> Bool)
-pastEnd = $$(compile [|| \(end::EndDate) (current::Integer) -> case end of
-    Fixed n -> n `lessThanEqualsInteger` current
-    Never   -> False
+pastEnd :: PlutusTx.CompiledCode (EndDate -> Builtins.Integer -> PlutusTx.Bool)
+pastEnd = $$(PlutusTx.compile [|| \(end::EndDate) (current::Builtins.Integer) -> case end of
+    Fixed n -> n `Builtins.lessThanEqualsInteger` current
+    Never   -> PlutusTx.False
   ||])
 -- BLOCK7
 -- | Check whether a given time is past the end date.
-pastEnd' :: CompiledCode (EndDate -> Integer -> Bool)
-pastEnd' = $$(compile [|| \(end::EndDate) (current::Integer) -> case end of
-    Fixed n -> n < current
-    Never   -> False
+pastEnd' :: PlutusTx.CompiledCode (EndDate -> Builtins.Integer -> PlutusTx.Bool)
+pastEnd' = $$(PlutusTx.compile [|| \(end::EndDate) (current::Builtins.Integer) -> case end of
+    Fixed n -> n PlutusTx.< current
+    Never   -> PlutusTx.False
   ||])
 -- BLOCK8
-addOne :: CompiledCode (Integer -> Integer)
-addOne = $$(compile [|| \(x:: Integer) -> x `addInteger` 1 ||])
+addOne :: PlutusTx.CompiledCode (Builtins.Integer -> Builtins.Integer)
+addOne = $$(PlutusTx.compile [|| \(x:: Builtins.Integer) -> x `Builtins.addInteger` 1 ||])
 -- BLOCK9
-addOneToN :: Integer -> CompiledCode Integer
+addOneToN :: Builtins.Integer -> PlutusTx.CompiledCode Builtins.Integer
 addOneToN n =
     addOne
     -- 'applyCode' applies one 'CompiledCode' to another.
-    `applyCode`
+    `PlutusTx.applyCode`
     -- 'liftCode' lifts the argument 'n' into a
     -- 'CompiledCode Integer'.
     liftCode n
@@ -164,12 +164,12 @@ addOneToN n =
 -- 'makeLift' generates instances of 'Lift' automatically.
 makeLift ''EndDate
 
-pastEndAt :: EndDate -> Integer -> CompiledCode Bool
+pastEndAt :: EndDate -> Builtins.Integer -> PlutusTx.CompiledCode PlutusTx.Bool
 pastEndAt end current =
     pastEnd
-    `applyCode`
+    `PlutusTx.applyCode`
     liftCode end
-    `applyCode`
+    `PlutusTx.applyCode`
     liftCode current
 
 {- |