Merge pull request #1433 from Plutonomicon/develop

Prepare for v5.0.0

.gitignore

@@ -21,5 +21,6 @@ output.js
 .idea/
 test-data/chrome-user-data
 test-data/preview
+test-data/keys
 tmp
 node_modules

CHANGELOG.md

@@ -7,40 +7,88 @@ 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 -->
 
-- [[v4.0.2] - 2023-01-17](#v402---2023-01-17)
-  - [Fixed](#fixed)
-- [[v4.0.1] - 2022-12-20](#v401---2022-12-20)
+- [[v5.0.0]](#v500)
   - [Added](#added)
-- [[v4.0.0] - 2022-12-15](#v400---2022-12-15)
-  - [Added](#added-1)
   - [Changed](#changed)
   - [Removed](#removed)
-  - [Fixed](#fixed-1)
+  - [Fixed](#fixed)
   - [Runtime Dependencies](#runtime-dependencies)
-- [[3.0.0] - 2022-11-21](#300---2022-11-21)
+- [[v4.0.2] - 2023-01-17](#v402---2023-01-17)
+  - [Fixed](#fixed-1)
+- [[v4.0.1] - 2022-12-20](#v401---2022-12-20)
+  - [Added](#added-1)
+- [[v4.0.0] - 2022-12-15](#v400---2022-12-15)
   - [Added](#added-2)
   - [Changed](#changed-1)
   - [Removed](#removed-1)
   - [Fixed](#fixed-2)
   - [Runtime Dependencies](#runtime-dependencies-1)
-- [[2.0.0] - 2022-09-12](#200---2022-09-12)
+- [[3.0.0] - 2022-11-21](#300---2022-11-21)
   - [Added](#added-3)
   - [Changed](#changed-2)
   - [Removed](#removed-2)
   - [Fixed](#fixed-3)
-- [[2.0.0-alpha] - 2022-07-05](#200-alpha---2022-07-05)
+  - [Runtime Dependencies](#runtime-dependencies-2)
+- [[2.0.0] - 2022-09-12](#200---2022-09-12)
   - [Added](#added-4)
-  - [Removed](#removed-3)
   - [Changed](#changed-3)
+  - [Removed](#removed-3)
   - [Fixed](#fixed-4)
-- [[1.1.0] - 2022-06-30](#110---2022-06-30)
+- [[2.0.0-alpha] - 2022-07-05](#200-alpha---2022-07-05)
+  - [Added](#added-5)
+  - [Removed](#removed-4)
+  - [Changed](#changed-4)
   - [Fixed](#fixed-5)
-- [[1.0.1] - 2022-06-17](#101---2022-06-17)
+- [[1.1.0] - 2022-06-30](#110---2022-06-30)
   - [Fixed](#fixed-6)
+- [[1.0.1] - 2022-06-17](#101---2022-06-17)
+  - [Fixed](#fixed-7)
 - [[1.0.0] - 2022-06-10](#100---2022-06-10)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+## [v5.0.0]
+
+### Added
+
+- **Blockfrost support** - see [`blockfrost.md`](./doc/blockfrost.md) ([#1260](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1260))
+- A test runner interface for Blockfrost (`Contract.Test.Blockfrost`). See [`blockfrost.md`](./doc/blockfrost.md) ([#1420](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1420))
+- `blake2b224Hash` and `blake2b224HashHex` functions for computing blake2b-224 hashes of arbitrary byte arrays ([#1323](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1323))
+- `bundlePursProject` allows passing of `includeBundledModule` flag to export the bundled JS module `spago bundle-module` outputs
+- `Contract.Transaction` exports `mkPoolPubKeyHash` and `poolPubKeyHashToBech32` for bech32 roundtripping ([#1360](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1360))
+- `Contract.isTxConfirmed` function to check if a transaction is confirmed at the moment.
+
+### Changed
+
+- **Contract interface change:** `Contract` does not have a row type parameter anymore. Use `ReaderT` or pass values explicitly to access them during runtime.
+- **Contract interface change:** `ConfigParams r` is replaced by `ContractParams` with the same purpose.
+- `SystemStart` now has `DateTime` (rather than `String`) as the underlying type ([#1377](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1377))
+- `EraSummaries` now does not have an `EncodeAeson` instance. Consider wrapping it in `OgmiosEraSummaries` for Aeson encoding. ([#1377](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1377))
+- Testing interface is re-implemented. Assertion functions from `Contract.Test.Utils` are moved to `Contract.Test.Assert`. See [the docs](./doc/test-utils.md) for info on the new interface. ([#1389](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1389))
+- Balancer no longer selects UTxOs which use PlutusV2 features when the transaction contains PlutusV1 scripts ([#1349](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1349))
+- `startPlutipCluster` error message now includes cluster startup failure details. ([#1407](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1407))
+- `PlutipTest` is now known as `Contract.Test.ContractTest`. It has been semantically untied from Plutip, because we now have another test runner for tests that rely on particular funds distributions - [Blockfrost](./doc/blockfrost.md). See `Contract.Test.Blockfrost.runContractTestsWithBlockfrost` ([#1260](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1260))
+- `Contract.Staking.getPoolParameters` has been moved to `Contract.Backend.Ogmios.getPoolParameters`. This function only runs with Ogmios backend, because Blockfrost [does not provide](https://github.com/blockfrost/blockfrost-backend-ryo/issues/82) all the required values ([#1260](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1260))
+- Use of [CIP-40](https://cips.cardano.org/cips/cip40/) collateral output is now enabled with CIP-30 wallets ([#1260](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1260)).
+- `reindexSpentScriptRedeemers` is no longer in Contract (it's pure) ([#1260](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1260))
+
+### Removed
+
+- **Important** [Ogmios Datum Cache](https://github.com/mlabs-haskell/ogmios-datum-cache) is no longer a runtime dependency of CTL, as well as its Postgres DB - if updating, remove them from your runtime.
+
+### Fixed
+- CIP-25 strings are now being split into chunks whose sizes are less than or equal to 64 to adhere to the CIP-25 standard ([#1343](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1343))
+- Critical upstream fix in [`purescript-bignumber`](https://github.com/mlabs-haskell/purescript-bignumber/pull/2)
+- `OutputDatum` aeson encoding now roundtrips ([#1388](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1388))
+- Fix incorrect redeemer indexing for Plutus stake validator scripts ([#1417](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1417))
+
+### Runtime Dependencies
+
+- [Ogmios](https://github.com/mlabs-haskell/ogmios) - v5.5.7
+- [Kupo](https://github.com/CardanoSolutions/kupo) - v2.2.0
+- [Cardano-Node](https://github.com/input-output-hk/cardano-node/) - v1.35.4
+- [Plutip](https://github.com/mlabs-haskell/plutip) - commit 8d1795d9ac3f9c6f31381104b25c71576eeba009
+
 ## [v4.0.2] - 2023-01-17
 
 ### Fixed
@@ -65,6 +113,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 - Running plutip servers attaches on SIGINT handlers and therefore node will not exit by default. ([#1231](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1231)).
 - `TestPlanM`, `interpret` and `interpretWithConfig` are now public in `Contract.Test.Mote` and our custom `consoleReporter` in `Contract.Test.Mote.ConsoleReporter`. ([#1261](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1261)).
+- Internal datum conversions are now total, resulting in some datum-related Contract functions dropping the use of `Maybe`, for example `datumHash`, `convertPlutusData` and their related functions. ([#1284](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1284)).
 - CIP-25 `policy_id` and `asset_name` metadata keys no longer include a `0x` prefix for compatibility with Blockfrost ([#1309](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1309)).
 - `purescript-aeson` package has been updated:
   - the performance has generally been improved

Makefile

@@ -1,12 +1,11 @@
 SHELL := bash
 .ONESHELL:
-.PHONY: run-dev run-build check-format format run-datum-cache-postgres-console
-		query-testnet-tip clean check-explicit-exports
+.PHONY: run-dev run-build check-format format query-testnet-tip clean check-explicit-exports
 .SHELLFLAGS := -eu -o pipefail -c
 
-ps-sources := $(shell fd -epurs -Etmp)
-nix-sources := $(shell fd -enix --exclude='spago*' -Etmp)
-js-sources := $(shell fd -ejs -Etmp)
+ps-sources := $(shell fd --no-ignore-parent -epurs)
+nix-sources := $(shell fd --no-ignore-parent -enix --exclude='spago*')
+js-sources := $(shell fd --no-ignore-parent -ejs)
 ps-entrypoint := Ctl.Examples.ByUrl # points to one of the example PureScript modules in examples/
 ps-bundle = spago bundle-module -m ${ps-entrypoint} --to output.js
 preview-node-ipc = $(shell docker volume inspect store_node-preview-ipc | jq -r '.[0].Mountpoint')
@@ -47,9 +46,6 @@ format:
 	make check-examples-imports
 	make check-whitespace
 
-run-datum-cache-postgres-console:
-	@nix shell nixpkgs#postgresql -c psql postgresql://ctxlib:ctxlib@localhost:5432
-
 query-preview-testnet-tip:
 	CARDANO_NODE_SOCKET_PATH=${preview-node-ipc}/node.socket cardano-cli query tip \
 	  --testnet-magic 2

README.md

@@ -2,37 +2,55 @@
 
 [![Hercules-ci][herc badge]][herc link]
 [![Cachix Cache][cachix badge]][cachix link]
+[![PureScript code documentation][docs badge]][docs link]
 
 [herc badge]: https://img.shields.io/badge/ci--by--hercules-green.svg
 [herc link]: https://hercules-ci.com/github/Plutonomicon/cardano-transaction-lib
 [cachix badge]: https://img.shields.io/badge/cachix-public_plutonomicon-blue.svg
 [cachix link]: https://public-plutonomicon.cachix.org
+[docs badge]: https://img.shields.io/badge/docs-PureScript%20code%20documentation-%2377F
+[docs link]: https://plutonomicon.github.io/cardano-transaction-lib/
 
-**cardano-transaction-lib** (CTL) is a Purescript library for building smart contract transactions on Cardano. It aims to port the functionality and interface of Plutus off-chain code to the browser environment.
+**cardano-transaction-lib** (CTL) is a Purescript library for building smart contract transactions on Cardano. It aims to port the functionality and interface of Plutus off-chain code to the browser environment and NodeJS.
 
 **Table of Contents**
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Roadmap](#roadmap)
-  - [Light wallet support](#light-wallet-support)
 - [Documentation](#documentation)
+  - [Light wallet support](#light-wallet-support)
+- [Roadmap](#roadmap)
 - [Architecture](#architecture)
 - [Additional resources/tools:](#additional-resourcestools)
 - [Available support channels info](#available-support-channels-info)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Roadmap
+## Documentation
 
-- [x] **Stage 1** Build a simple transaction in the browser that works with at least one light wallet (Nami)
-- [x] **Stage 2** Once we can construct a simple user-to-user transaction, we will try to use the library to submit the tx with nami
-- [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**)
+Please explore our documentation to discover how to use CTL, how to set up its runtime, and how it compares to Plutus/PAB:
+
+- [Super quick start](./doc/getting-started.md#setting-up-a-new-project)
+- [Adding CTL as a dependency](./doc/ctl-as-dependency.md)
+- [CTL's runtime dependencies](./doc/runtime.md)
+- [Blockfrost support](./doc/blockfrost.md)
+- [Getting started writing CTL contracts](./doc/getting-started.md)
+- [Migrating from Plutus to CTL](./doc/plutus-comparison.md)
+- [Testing overview](./doc/testing.md)
+  - [Testing contracts with Plutip](./doc/plutip-testing.md)
+  - [End-to-end testing with headless browsers](./doc/e2e-testing.md)
+  - [Utilities for testing](./doc/test-utils.md)
+- [CIP-25 NFT standard support](./doc/cip-25-nfts.md)
+- [Transaction balancing](./doc/balancing.md)
+- [Transaction chaining](./doc/tx-chaining.md)
+- [Ada staking support](./doc/staking.md)
+- [SECP256k1 support (CIP-49)](./doc/secp256k1-support.md)
+- [FAQs](./doc/faq.md)
+- [Feature overview video](./doc/video-intro.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).
 
 ### Light wallet support
 
@@ -48,20 +66,15 @@ Support is planned for the following light wallets:
 - [ ] [Typhon](https://typhonwallet.io/)
 - [ ] [Yoroi](https://yoroi-wallet.com/)
 
-## Documentation
-
-Please explore our documentation to discover how to use CTL, how to set up its runtime, and how it compares to Plutus/PAB:
-
-- [Super quick start](./doc/getting-started.md#setting-up-a-new-project)
-- [FAQs](./doc/faq.md)
-- [Migrating from Plutus to CTL](./doc/plutus-comparison.md)
-- [Adding CTL as a dependency](./doc/ctl-as-dependency.md)
-- [Getting started writing CTL contracts](./doc/getting-started.md)
-- [CTL's runtime dependencies](./doc/runtime.md)
-- [Developing on CTL](./doc/development.md)
-- [Testing contracts with Plutip](./doc/plutip-testing.md)
+## Roadmap
 
-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).
+- [x] **Stage 1** Build a simple transaction in the browser that works with at least one light wallet (Nami)
+- [x] **Stage 2** Once we can construct a simple user-to-user transaction, we will try to use the library to submit the tx with nami
+- [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**)
 
 ## Architecture
 
@@ -71,16 +84,15 @@ 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 an alternative BlockFrost backend as well in the future
+   - 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)?
-   - `ogmios-datum-cache` solves this problem
-4. How do we submit the transaction?
+   - `Kupo` solves this problem
+4. 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?
    - 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 (e.g. CTL's `DatumType` and `RedeemerType` are type class with fundeps, as Purescript lacks any notion of type families/type-level functions)
-6. A lingering concern remains around storage solutions, if needed
-   - This can be in memory, in various browser storage solutions, or a decentralized DB like Fluree
+   - 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
 
 ## Additional resources/tools: