Merge branch 'develop' into dshuiski/conway

Author: errfrom

.gitignore

@@ -29,3 +29,4 @@ node_modules
 plutip-server/dist-newstyle/
 plutip-server/dist/
 plutip-server/.stack-work/
+nixos.qcow2

CHANGELOG.md

@@ -7,7 +7,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [[Unreleased]](#unreleased)
+- [[v9.0.0]](#v900)
+  - [Deprecated](#deprecated)
   - [Added](#added)
   - [Removed](#removed)
   - [Changed](#changed)
@@ -67,17 +68,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## [Unreleased]
+## [v9.0.0]
+
+### Deprecated
+
+> [!WARNING]
+> **IMPORTANT** Constraints interface (`Contract.TxConstraints` & `Contract.ScriptLookups`) has been deprecated and will be removed in a future version. Please use [`purescript-cardano-transaction-builder`](https://github.com/mlabs-haskell/purescript-cardano-transaction-builder) (via `Contract.Transaction.buildTx`) for new contracts. The motivation for deprecation is that it was unnecessarily complex, not flexible enough, and existed only because of the desire to provide code-level compatibility with PAB. See [this Catalyst proposal](https://cardano.ideascale.com/c/idea/101478) for more info.
 
 ### Added
 
+- `Contract.Transaction.buildTx :: Array TransactionBuilderStep -> Contract Transaction` that provides a `Contract`-based interface for the [new transaction builder](https://github.com/mlabs-haskell/purescript-cardano-transaction-builder).
+- `Contract.Transaction.submitTxFromBuildPlan :: UtxoMap -> BalanceTxConstraintsBuilder -> Array TransactionBuilderStep -> Contract Transaction` - a convenience function that executes the whole transaction creation pipeline starting from a build plan for [the new transaction builder](https://github.com/mlabs-haskell/purescript-cardano-transaction-builder).
+- `Contract.ClientError.pprintClientError` to provide readable error reports.
+- `Contract.Staking.getStakeCredentialDelegationsAndRewards` utility function
+
 ### Removed
 
-- `Contract.Scripts.applyArgs` - use `Cardano.Plutus.ApplyArgs.applyArgs` from [purescript-uplc-apply-args](https://github.com/mlabs-haskell/purescript-uplc-apply-args)
+- **IMPORTANT** `UnbalancedTx` type has been removed. This change was motivated by the fact that `UnbalancedTx` existed simply to tie together transaction building and balancing by keeping extra context. Now that transaction builder is placed in [its own package](https://github.com/mlabs-haskell/purescript-cardano-transaction-builder), there is no more need in `UnbalancedTx`, that is not used with the new builder.
+- **IMPORTANT** `balanceTxWithConstraints`, `balanceTxWithConstraintsE` - use `balanceTx`
+- **IMPORTANT** `balanceTxsWithConstraints` - use `balanceTxs`
+- **IMPORTANT** `withBalancedTxWithConstraints`, `withBalancedTxWithConstraints` - use `withBalancedTxs`
+- **IMPORTANT** `Contract.Scripts.applyArgs` - use `Cardano.Plutus.ApplyArgs.applyArgs` from [purescript-uplc-apply-args](https://github.com/mlabs-haskell/purescript-uplc-apply-args).
+- `Contract.Transaction.submitTxFromConstraintsReturningFee` - too niche use case to be allowed in the public API.
+- `Contract.Transaction` lens values. Use lenses from `Cardano.Types.Transaction`
 
 ### Changed
 
 - Bumped Ogmios to version 6.0.3 ([#1626](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1626))
+- `Contract.Transaction.mkUnbalancedTx` now returns a tuple: a transaction and the UTxOs it used.
+- `Contract.Transaction.balanceTx` accepts two extra argument: a list of used UTxOs (set to `Data.Map.empty` if none of them are coming from the outside of the wallet) and balancer constraints (set to `mempty` if not needed)
+- Default synchronization parameters: all [wallet <-> query layer synchronization primitives](./doc/query-layers.md) are now off by default. The reason is that the runtime overhead made the users unhappy and it was not worth it for most of the users. If your dApp sends transactions in quick succession, consider enabling the synchronization again by using `softSynchronizationParams` (old behavior) or `strictSynchronizationParams`.
+- `BalanceTxConstraintsBuilder` has been renamed to `BalancerConstraints`. It is still available under the old name as a type synonym.
 
 ### Fixed
 

Makefile

@@ -101,11 +101,8 @@ query-preprod-testnet-tip:
 	CARDANO_NODE_SOCKET_PATH=${preprod-node-ipc}/node.socket cardano-cli query tip \
 	  --testnet-magic 1
 
-run-ci-actions:
+run-ci-actions: run-template-checks
 	nix build -L .#checks.x86_64-linux.formatting-check
-	nix build -L .#checks.x86_64-linux.template-deps-json
-	nix build -L .#checks.x86_64-linux.template-dhall-diff
-	nix build -L .#checks.x86_64-linux.template-version
 	nix build -L .#checks.x86_64-linux.ctl-unit-test
 	nix build -L .#checks.x86_64-linux.ctl-e2e-test
 	nix build -L .#checks.x86_64-linux.ctl-local-testnet-test

doc/babbage-features.md

@@ -6,48 +6,29 @@ This document is a reference/explainer for the new CTL APIs introduced for Babba
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Reference Inputs](#reference-inputs)
-- [Reference Scripts](#reference-scripts)
+- [Reference Inputs & Reference Scripts](#reference-inputs--reference-scripts)
 - [Inline Data](#inline-data)
 - [Collateral Output](#collateral-output)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
-## Reference Inputs
+## Reference Inputs & Reference Scripts
 
 [Reference inputs](https://cips.cardano.org/cip/CIP-0031#reference-inputs) allow looking at an output without spending it in Plutus scripts.
 
-There are two ways to use an input as a reference in the constraints API:
-
-1. via `mustReferenceOutput`, which allows Plutus scripts to access the information (e.g. datum, locked value) contained in the output.
-
-[Usage example](../examples/PlutusV2/ReferenceInputs.purs)
-
-2. by providing constraints which accept a value of the type `InputWithScriptRef` with the `RefInput` constructor. These allow scripts (validating or minting) to be reused by reference between multiple transactions without including them in those transactions, explained further in [Reference Scripts](#reference-scripts).
-
-[Usage example](../examples/PlutusV2/ReferenceInputsAndScripts.purs)
-
-## Reference Scripts
-
 [Reference Scripts](https://cips.cardano.org/cip/CIP-0033) allows the use of scripts without attaching them to the transaction (and using a reference instead).
 
-Reference scripts can be utilized in CTL by first creating a reference point for the script to be used later via `mustPayToScriptWithScriptRef` (or its variants).
+Reference scripts can be utilized in CTL by first creating a UTxO containing the script to be used later.
 
-This constraint utilises a new `ScriptRef` type that includes either a native script or a Plutus script.
-
-Then, `mustSpendScriptOutputUsingScriptRef` (or its variants) can be used to use a reference script. It accepts a value of type `InputWithScriptRef` that specifies whether the UTxO with the reference script should be spent or referenced.
-
-[Usage example](../examples/PlutusV2/ReferenceScripts.purs)
+[Usage example](../examples/PlutusV2/ReferenceInputsAndScripts.purs)
 
 ## Inline Data
 
 [CIP-32](https://cips.cardano.org/cip/CIP-0032) introduces the inline data feature that allows storing datum values directly in transaction outputs, instead of just the hashes.
 
-In CTL, alternating between datum storage options can be achieved by specifying a `DatumPresence` value with constraints that accept it, like `mustPayToPubKeyWithDatum`.
-
-[Usage example](../examples/PlutusV2/InlineDatum.purs)
-
 ## Collateral Output
 
 [CIP-40](https://cips.cardano.org/cip/CIP-0040) introduces explicit collateral output. On validation failure, previously the entire collateral was consumed. Now, if excess collateral is supplied, even with native assets, the surplus can be returned on validation failure.
 
 Collateral output is automatically added to transactions in CTL. To trigger a collateral return, the `mustNotBeValid` constraint should be explicitly specified, otherwise a script error would be detected earlier and the transaction will not be sent.
+
+[Usage example](../examples/Lose7Ada.purs)

doc/balancing.md

@@ -1,7 +1,7 @@
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Configuring balancing process](#configuring-balancing-process)
+- [Configuring the balancing process](#configuring-the-balancing-process)
   - [Balancer constraints](#balancer-constraints)
   - [Concurrent spending](#concurrent-spending)
   - [Balancing a Tx for other wallet](#balancing-a-tx-for-other-wallet)
@@ -10,7 +10,7 @@
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-# Configuring balancing process
+# Configuring the balancing process
 
 Transaction balancing in Cardano is the process of finding a set of inputs and outputs that that sum up to zero, covering all the required fees for the transaction to be valid.
 
@@ -37,7 +37,7 @@ Setting `mustUseUtxosAtAddress`, `mustSendChangeToAddress` and `mustUseCollatera
 
 ## Synchronization
 
-Before balancing, CTL tries to synchronize the wallet state with the query layer, i.e. waits until all UTxOs that the wallet returns are visible in the query layer. Thus the situation when the query layer refuses to validate a Tx (either during ex-units evaluation or on Tx submission) is only possible due to a rollback or a synchronization timeout. Please see [our docs for query layer synchronization](./query-layers.md).
+It's possible to make CTL try to synchronize the wallet state with the query layer, i.e. wait until all UTxOs that the wallet returns are visible in the query layer. Thus the situation when the query layer refuses to validate a Tx (either during ex-units evaluation or on Tx submission) is only possible due to a rollback or a synchronization timeout. Please see [our docs for query layer synchronization](./query-layers.md).
 
 ## Balancing process limitations
 

doc/development.md

@@ -22,6 +22,7 @@ This document outlines development workflows for CTL itself. You may also wish t
   - [JS](#js)
 - [Switching development networks](#switching-development-networks)
 - [Maintaining the template](#maintaining-the-template)
+- [Updating the template](#updating-the-template)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -148,4 +149,13 @@ Set new `network.name` and `network.magic` in `runtime.nix`. Also see [Changing
 
 [The template](../templates/ctl-scaffold/) must be kept up-to-date with the repo. Although there are some checks for common problems in CI, it's still possible to forget to update the `package-lock.json` file.
 
+## Updating the template
+
+1. Update the revision of CTL in the template's `flake.nix`
+2. Update the npm packages in the `package.json` (if needed)
+3. Run `npm i` to update the lockfile (if there are NPM dependency version changes)
+4. Update the revisions in the template's `packages.dhall` (CTL version must match the one in `flake.nix`)
+5. Run `spago2nix generate`
+6. Run `nix develop`
+
 [This helper script](../scripts/template-check.sh) can be used to make sure the template can be initialized properly from a given revision.

doc/getting-started.md

@@ -16,11 +16,6 @@ This guide will help you get started writing contracts with CTL. Please also see
 - [Executing contracts and the `ContractEnv`](#executing-contracts-and-the-contractenv)
   - [Making the `ContractEnv`](#making-the-contractenv)
 - [Building and submitting transactions](#building-and-submitting-transactions)
-  - [Using compiled scripts](#using-compiled-scripts)
-- [Testing](#testing)
-  - [Without a light wallet](#without-a-light-wallet)
-  - [With a light wallet](#with-a-light-wallet)
-  - [Cardano Testnet integration](#cardano-testnet-integration)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -56,7 +51,7 @@ You can learn more about using CTL as a dependency [here](./ctl-as-dependency.md
 
 ### Other prerequisites
 
-You will also need to become familiar with [CTL's runtime](./runtime.md) as its runtime services are required for executing virtually all contracts.
+You will also need to become familiar with [CTL's runtime](./runtime.md) as its runtime services are required for executing virtually all contracts. If you want to avoid manual backend setup, use [blockfrost.io](./blockfrost.md).
 
 ## Importing CTL modules
 
@@ -140,9 +135,13 @@ main = Contract.Monad.launchAff_ do -- we re-export this for you
         , kupoConfig: defaultKupoServerConfig
         }
       , networkId: TestnetId
-      , logLevel: Trace
       , walletSpec: Just ConnectToNami
+      , logLevel: Trace
       , customLogger: Nothing
+      , suppressLogs: false
+      , hooks: emptyHooks
+      , timeParams: defaultTimeParams
+      , synchronizationParams: defaultSynchronizationParams
       }
   runContract config someContract
 
@@ -167,49 +166,49 @@ customOgmiosWsConfig =
 
 Unlike PAB, CTL obscures less of the build-balance-sign-submit pipeline for transactions and most of the steps are called individually. The general workflow in CTL is similar to the following:
 
-- Build a transaction using `Contract.ScriptLookups`, `Contract.TxConstraints` and `Contract.BalanceTxConstraints` (it is also possible to directly build a `Transaction` if you require even greater low-level control over the process, although we recommend the constraints/lookups approach for most users):
+- Build a transaction using [`cardano-transaction-builder`](https://github.com/mlabs-haskell/purescript-cardano-transaction-builder):
 
   ```purescript
   contract = do
     let
-      constraints :: TxConstraints Unit Unit
-      constraints =
-        TxConstraints.mustPayToScript vhash unitDatum
-          (Value.lovelaceValueOf $ BigInt.fromInt 2_000_000)
-
-      lookups :: ScriptLookups PlutusData
-      lookups = ScriptLookups.validator validator
-
-      balanceTxConstraints :: BalanceTxConstraints.BalanceTxConstraintsBuilder
-      balanceTxConstraints =
-        BalanceTxConstraints.mustUseUtxosAtAddress address
-          <> BalanceTxConstraints.mustSendChangeToAddress address
-          <> BalanceTxConstraints.mustNotSpendUtxoWithOutRef nonSpendableOref
-
-    -- `liftedE` will throw a runtime exception on `Left`s
-    unbalancedTx <- liftedE $ Lookups.mkUnbalancedTx lookups constraints
+      plan =
+        [ Pay $ TransactionOutput
+          { address: address
+          , amount: Value.lovelaceValueOf $ BigNum.fromInt 1_000_000
+          , datum: Just $ OutputDatumHash $ hashPlutusData PlutusData.unit
+          , scriptRef: Nothing
+          }
+        ]
+    unbalancedTx <- buildTx plan
     ...
   ```
 
-- Balance it using `Contract.Transaction.balanceTx` (or `Contract.Transaction.balanceTxWithConstraints` if you need to adjust the balancer behaviour) and then sign it using `signTransaction`:
+- Balance it using `Contract.Transaction.balanceTx`, and then sign it using `signTransaction`:
   ```purescript
   contract = do
     ...
+    let
+      balanceTxConstraints :: BalanceTxConstraints.BalanceTxConstraintsBuilder
+      balanceTxConstraints =
+        BalanceTxConstraints.mustUseUtxosAtAddress address
+          <> BalanceTxConstraints.mustSendChangeToAddress address
+          <> BalanceTxConstraints.mustNotSpendUtxoWithOutRef nonSpendableOref
     -- `liftedE` will throw a runtime exception on `Left`s
     balancedTx <-
-      liftedE $ balanceTxWithConstraints unbalancedTx balanceTxConstraints
+      balanceTx unbalancedTx usedUtxos balanceTxConstraints
     balancedSignedTx <- signTransaction balancedTx
     ...
   ```
 
-- Submit using `Contract.Transaction.submit`:
+- Submit using `Contract.Transaction.submit` and await for confirmation using `awaitTxConfirmed`:
 
   ```purescript
   contract = do
     ...
     txId <- submit balancedSignedTx
+    awaitTxConfirmed txId
     logInfo' $ "Tx ID: " <> show txId
-  ```
+```
 
 ### Using compiled scripts