Merge branch 'develop' into alexey/pool-pkh-data-instances

.mlc_config.json

@@ -2,6 +2,9 @@
     "ignorePatterns": [
         {
             "pattern": "^https://gerowallet.io"
+        },
+        {
+            "pattern": "^https://iohk.io"
         }
     ],
     "aliveStatusCodes": [

CHANGELOG.md

@@ -56,6 +56,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Added
 
+- Added `extraSources` and `data` features to CTL's Nix build function ([#1516](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1516))
 - Added several `Ring`-like numeric instances for `Coin` ([#1485](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1485))
 - Added `ToData` and `FromData` instances for `PoolPubKeyHash` ([#1483](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1483))
 - **[IMPORTANT]** New machinery to achieve better synchronization between wallets and query layer has been added. This affects all CTL-based apps when light wallet browser extensions are in use. See [here](./doc/query-layers.md) for more info ([#1440](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1440))
@@ -67,9 +68,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Configuration options for Kupo in `buildCtlRuntime` ([`deferDbIndexes`](https://cardanosolutions.github.io/kupo/#section/Getting-started/-defer-db-indexes) and [`pruneUtxo`](https://cardanosolutions.github.io/kupo/#section/Getting-started/-prune-utxo)) ([#1448](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1448))
 - `Contract.JsSdk` module containing helper functions for developers who want to use CTL from JS. See also: [this new guide](./doc/using-from-js.md) ([#1453](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1453))
 - New [docs for contract environment](./doc/contract-environment.md) ([#1453](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1453))
+- Cluster configuration options to `PlutipConfig`: `epochSize`, `maxTxSize` and `raiseExUnitsToMax` - see [Plutip docs](./doc/plutip-testing.md) ([#1494](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1494))
+- [HD wallet support](./doc/key-management.md) with mnemonic seed phrases ([#1498](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1498))
+- Ogmios-specific functions for Local TX Monitor Ouroboros Mini-Protocol in `Contract.Backend.Ogmios` ([#1508](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1508/))
+- New `mustSendChangeWithDatum` balancer constraint that adds datum to all change outputs ([#1510](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1510/))
+- Support for generic CIP-30 wallets by name ([#1524](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1524))
 
 ### Changed
 
+- `scriptCurrencySymbol` no longer returns `Maybe`
+  ([#1538](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1538)
 - **[IMPORTANT]** It is no more recommended to use `utxosAt` to get UTxOs at light wallet addresses. It may be a source of application bugs in some cases due to how wallets operate. Please see *Synchronization and wallet UTxO locking* section [here](./doc/query-layers.md) ([#1440](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1440))
 - Slot to/from POSIXTime conversion functions now live outside of `Effect` ([#1490](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1490))
 - All uses of `utxosAt` call have been replaced with `getWalletUtxos` in the balancer ([#1440](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1440))
@@ -88,6 +96,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Do not require light wallet collateral for all interactions ([#1477](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1477))
 - Removed re-exports of wallet-related functions from `Contract.Utxos` and `Contract.Address` (use `Contract.Wallet`) ([#1477](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1477))
 - `ownPaymentPubKeysHashes` renamed to `ownPaymentPubKeyHashes`, `ownStakePubKeysHashes` renamed to `ownStakePubKeyHashes` and both moved to `Contract.Wallet` ([#1477](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1477))
+- UTxO lists and combined input/output/mint/fee values are now being pretty-printed instead of logged using `Show` instance (in the balancer) ([#1531](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1531))
 
 ### Fixed
 
@@ -103,11 +112,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Output correct reward address in CIP-30 mock ([#1440](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1440))
 - Add a single-slot wait at Plutip startup before attempting to query any wallet UTxOs ([#1470](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1470))
 - Index `Reward` redeemers properly ([#1419](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1419),  [#1462](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1462))
+- A problem with collateral selection not respecting `mustNotSpendUtxosWithOutRefs` ([#1509](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1509))
+- A problem with too many change UTxOs being generated ([#1530](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1530))
 
 ### Removed
 
 - `E2E_SKIP_JQUERY_DOWNLOAD` configuration variable for [E2E test suite](./doc/e2e-testing.md). It is not needed, because it's expected value can be determined from the environment, and thus it can be an implementation detail ([#1440](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1440))
 - `reindexSpentScriptRedeemers` function from the public API - if there is a need to modify the `Transaction` in a way that breaks redeemer indices, it should be done before balancing ([#1462](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1462))
+- Typed scripts and constraints interface. In practice, it means that the following types now have no type-level arguments: `TxConstraints`, `ScriptLookups`.
 
 ## [v5.0.0]
 

README.md

@@ -48,10 +48,12 @@ Please explore our documentation to discover how to use CTL, how to set up its r
 - [Transaction balancing](./doc/balancing.md)
 - [Transaction chaining](./doc/tx-chaining.md)
 - [Ada staking support](./doc/staking.md)
+- [Key management](./doc/key-management.md)
 - [SECP256k1 support (CIP-49)](./doc/secp256k1-support.md)
 - [Custom query layers](./doc/custom-query-layers.md)
 - [FAQs](./doc/faq.md)
 - [Feature overview video](./doc/video-intro.md)
+- [Comparison with other frameworks (Lucid)](./doc/comparisons.md)
 - [Development workflows for CTL](./doc/development.md)
 
 You can also access [PureScript documentation for CTL and its dependencies](https://plutonomicon.github.io/cardano-transaction-lib/) for the most recent `develop` version, or [generate it yourself](./doc/development.md#generating-ps-documentation).
@@ -66,7 +68,7 @@ Support is planned for the following light wallets:
 - [x] [Lode](https://lodewallet.io/)
 - [x] [Eternl (formerly CCvault)](https://eternl.io/)
 - [x] [NuFi](https://nu.fi/)
-- [ ] [Lace](https://www.lace.io/)
+- [x] [Lace](https://www.lace.io/)
 - [ ] [Typhon](https://typhonwallet.io/)
 - [ ] [Yoroi](https://yoroi-wallet.com/)
 
@@ -77,8 +79,8 @@ Support is planned for the following light wallets:
 - [x] **Stage 3** Once we have a simple working transaction, we will seek to build a Plutus smart contract transaction with datum from scratch
 - [x] **Stage 4** Once we can construct Plutus smart contract transactions, we will seek to build a library/DSL/interface such that transactions can be built using constraints and lookups - as close as possible to a cut-and-paste solution from Plutus' `Contract` monad code in Haskell (but with no guarantee that code changes are not necessary)
   - [x] **Stage 4.1** Investigate supporting compatibility with the Vasil hardfork and improvements to our initial `Contract` API
-- [ ] **Stage 5** Once we have a basic `Contract`-style API, we will further refine its public interface, expand wallet support (see [below](#light-wallet-support)), expose a test interface (**DONE** - see [here](doc/plutip-testing.md)), provide a more ergonomic JS/TS API, support stake validators (**DONE**), and support CIP workflows on the public testnet (**In progress**)
-- [ ] **Stage 6** Once CTL's `Contract` interface has been stabilized, we will add support for even more wallets and attempt to deprecate CTL's currently required Haskell server (**DONE**)
+- [x] **Stage 5** Once we have a basic `Contract`-style API, we will further refine its public interface, expand wallet support (see [below](#light-wallet-support)), expose a test interface (**DONE** - see [here](doc/plutip-testing.md)), provide a more ergonomic JS/TS API, support stake validators (**DONE**), and support CIP workflows on the public testnet (**In progress**)
+- [x] **Stage 6** Once CTL's `Contract` interface has been stabilized, we will add support for even more wallets and attempt to deprecate CTL's currently required Haskell server (**DONE**)
 
 ## Architecture
 
@@ -88,12 +90,10 @@ CTL is directly inspired by the Plutus Application Backend (PAB). Unlike PAB, ho
    - This is handled by `cardano-serialization-lib`, a Rust library available as WASM
 2. How do we query the chain?
    - This has been solved using Ogmios & Kupo
-   - We [will support](https://cardano.ideascale.com/c/idea/420791) an alternative [BlockFrost](https://blockfrost.io/) backend as well in the future
-3. How do we query for datums (i.e. the datums themselves and not just their hashes)?
-   - `Kupo` solves this problem
-4. How do we get wallet data?
+   - Thanks to [Catalyst](https://cardano.ideascale.com/c/idea/420791), we now support an alternative [BlockFrost](https://blockfrost.io/) backend as well
+3. How do we get wallet data?
    - This is done via browser-based light wallet integration in the browser based on CIP-30
-5. How closely should we follow Plutus' `Contract` API?
+4. How closely should we follow Plutus' `Contract` API?
    - CTL's `Contract` model is **significantly** less restrictive than Plutus' and allows for arbitrary effects within the `Contract` monad
    - Certain features cannot be directly translated into Purescript from Haskell due to differences between the two languages
    - Some of the Plutus conventions do not make sense for us, due to differences between on-chain and off-chain

doc/comparisons.md

@@ -0,0 +1,64 @@
+<!-- H1 is used to skip the first header in the TOC -->
+<h1>CTL vs. other offchain solutions</h1>
+
+This document highlights key differences between CTL and other Cardano offchain frameworks.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Lucid](#lucid)
+  - [Wallet support](#wallet-support)
+  - [Query layer differences](#query-layer-differences)
+  - [Supported backends](#supported-backends)
+  - [Staking support](#staking-support)
+  - [Testing](#testing)
+  - [API design](#api-design)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Lucid
+
+### Wallet support
+
+- Lucid supports any CIP-30 compatible wallet. CTL supports a pre-defined list of wallets (however, the list can be extended easily).
+- Both CTL and Lucid support using [seed phrases and private keys](./key-management.md).
+- Lucid allows to use any address without a private key for querying - CTL does not allow that, but it's still possible to build transactions for other wallets to sign via [other means](./balancing.md).
+
+### Query layer differences
+
+Lucid uses a [`Provider` class](https://deno.land/x/[email protected]/mod.ts?s=Provider) that defines all available queries. CTL query methods are defined in [`QueryHandle`](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/src/Internal/Contract/QueryHandle/Type.purs#L36).
+
+CTL supports the following queries that Lucid does not:
+
+- `getScriptByHash`
+- `getTxMetadata`
+- `getChainTip`
+- `getCurrentEpoch`
+- `evaluateTx` (not needed for Lucid)
+- `getEraSummaries`
+- `getPoolIds`
+
+Lucid, on the other hand, provides a way to get a UTxO that contains a specified NFT (`getUtxoByUnit`).
+
+### Supported backends
+
+- Both CTL and Lucid support [Blockfrost](./blockfrost.md) and [Kupo+Ogmios](./runtime.md)
+- Lucid supports [Maestro](https://www.gomaestro.org/)
+- Both CTL and Lucid allow for custom backends - Lucid via `Provider` interface implementation, and CTL via a custom `QueryHandle`.
+
+### Staking support
+
+Both [CTL](./staking.md) and [Lucid](https://lucid.spacebudz.io/docs/getting-started/delegate/) support all operations with ADA delegations.
+
+### Testing
+
+CTL uses [Plutip](./plutip-testing.md), which is a tool to spawn real Cardano testnets on the fly, while Lucid uses an [emulator](https://lucid.spacebudz.io/docs/getting-started/test-emulate/).
+
+Additionally, CTL supports [testing with real wallets](./e2e-testing.md) via headless browsers and provides [an assertion library](./test-utils.md).
+
+### API design
+
+Lucid aims for simplicity, while CTL allows more fine-grained control over transaction building process.
+
+- CTL uses [`cardano-serialization-lib`](https://github.com/Emurgo/cardano-serialization-lib/), while Lucid uses a fork of [`cardano-multiplatform-lib`](https://github.com/berry-pool/cardano-multiplatform-lib). Lucid allows to use CML's `TxBuilder` or [call CML directly](https://lucid.spacebudz.io/docs/advanced/cml/), while CTL allows to alter the transaction arbitrarily as PureScript data type either before or after balancing. In CTL, CSL types and method wrappers are a part of the internal interface, but technically they can be used as well.
+- Plutus Data conversion is handled via a [schema-enabled API](https://lucid.spacebudz.io/docs/advanced/type-casting/) in Lucid. CTL allows for automatic `ToData` / `FromData` deriving for some types, via `HasPlutusSchema`.

doc/getting-started.md

@@ -38,6 +38,8 @@ Then, add `https://public-plutonomicon.cachix.org` and `public-plutonomicon.cach
 
 The easiest way to create a new CTL project is to use our `ctl-scaffold` flake template. This lives in the CTL repo -- you can have a look [here](../templates/ctl-scaffold). It contains a simple, yet complete, flakes-based scaffolding project with example `outputs` for a CTL project, including its runtime.
 
+Alternatively, consider [the-plutus-scaffold](https://github.com/mlabs-haskell/the-plutus-scaffold) flake template. It's a scaffold built on top of the above mentioned `ctl-scaffold`, but includes a react based frontend and a haskell onchain additionaly. It's more of a demo application, than a minimal working example.
+
 A new project can be initialized as follows:
 
 ```
@@ -217,15 +219,9 @@ You can import your scripts to use with CTL. See [importing-scripts](./importing
 
 ### Without a light wallet
 
-We provide `KeyWallet` to enable testing outside of the browser, or in-browser without a light wallet installed. To generate a key, you can use `cardano-cli` as follows:
-
-```shell
-$ cardano-cli address key-gen --normal-key --signing-key-file payment.skey --verification-key-file payment.vkey
-```
-
-The signing key can be loaded to CTL using `WalletSpec`'s `UseKeys` constructor. See [`examples/KeyWallet/Internal/Pkh2PkhContract.purs`](../examples/KeyWallet/Internal/Pkh2PkhContract.purs#L49).
+We provide `KeyWallet` to enable testing outside of the browser, or in-browser without a light wallet installed.
 
-From here you can submit transactions that will be signed with your private key, or perhaps export transactions to be tested with external tools such as [`plutip` testing tool](https://github.com/mlabs-haskell/plutip).
+See [here](./key-management.md)
 
 ### With a light wallet
 

doc/importing-scripts.md

@@ -4,12 +4,19 @@
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+- [Exporting scripts from Plutus](#exporting-scripts-from-plutus)
 - [Importing serialized scripts](#importing-serialized-scripts)
 - [Serializing Plutus scripts](#serializing-plutus-scripts)
   - [PlutusTx](#plutustx)
   - [Plutarch](#plutarch)
+  - [plutarch-ctl-bridge](#plutarch-ctl-bridge)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Exporting scripts from Plutus
+
+See [the-plutus-scaffold](https://github.com/mlabs-haskell/the-plutus-scaffold)'s [exporter](https://github.com/mlabs-haskell/the-plutus-scaffold/tree/main/onchain/exporter) for a pipeline example.
+
 ## Importing serialized scripts
 
 To use your own scripts, compile them to any subdirectory in the root of your project (where `webpack.config.js` is located) and add a relative path to `webpack.config.js` under the `resolve.alias` section. In CTL, we have the `Scripts` alias for this purpose. Note the capitalization of `Scripts`: it is necessary to disambiguate it from local folders.
@@ -138,3 +145,7 @@ Note that we specified plutus version.
 ### Plutarch
 
 You can use [`ply`](https://github.com/mlabs-haskell/ply) and [`ply-ctl`](https://github.com/mlabs-haskell/ply-ctl).
+
+### plutarch-ctl-bridge
+
+You can use [`plutarch-ctl-bridge`](https://github.com/mlabs-haskell/plutarch-ctl-bridge) to generate Purescript types from your Haskell type definitions and typed script wrappers from parametrized Plutarch scripts. See [example module](https://github.com/mlabs-haskell/plutarch-ctl-bridge/blob/main/example/Main.hs).