Merge pull request #1614 from Plutonomicon/develop

v8.0.0 release

.mlc_config.json

@@ -3,6 +3,9 @@
         {
             "pattern": "^https://gerowallet.io"
         },
+        {
+            "pattern": "^https://stackoverflow.com"
+        },
         {
             "pattern": "^https://singularitynet.io"
         },

CHANGELOG.md

@@ -9,55 +9,60 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 - [[Unreleased]](#unreleased)
   - [Added](#added)
+  - [Removed](#removed)
   - [Changed](#changed)
   - [Fixed](#fixed)
-  - [Removed](#removed)
-- [[v7.0.0]](#v700)
+- [[v8.0.0]](#v800)
   - [Added](#added-1)
   - [Changed](#changed-1)
   - [Fixed](#fixed-1)
   - [Removed](#removed-1)
-- [[v6.0.0]](#v600)
+- [[v7.0.0]](#v700)
   - [Added](#added-2)
   - [Changed](#changed-2)
   - [Fixed](#fixed-2)
   - [Removed](#removed-2)
-- [[v5.0.0]](#v500)
+- [[v6.0.0]](#v600)
   - [Added](#added-3)
   - [Changed](#changed-3)
-  - [Removed](#removed-3)
   - [Fixed](#fixed-3)
-  - [Runtime Dependencies](#runtime-dependencies)
-- [[v4.0.2] - 2023-01-17](#v402---2023-01-17)
-  - [Fixed](#fixed-4)
-- [[v4.0.1] - 2022-12-20](#v401---2022-12-20)
+  - [Removed](#removed-3)
+- [[v5.0.0]](#v500)
   - [Added](#added-4)
-- [[v4.0.0] - 2022-12-15](#v400---2022-12-15)
-  - [Added](#added-5)
   - [Changed](#changed-4)
   - [Removed](#removed-4)
+  - [Fixed](#fixed-4)
+  - [Runtime Dependencies](#runtime-dependencies)
+- [[v4.0.2] - 2023-01-17](#v402---2023-01-17)
   - [Fixed](#fixed-5)
-  - [Runtime Dependencies](#runtime-dependencies-1)
-- [[3.0.0] - 2022-11-21](#300---2022-11-21)
+- [[v4.0.1] - 2022-12-20](#v401---2022-12-20)
+  - [Added](#added-5)
+- [[v4.0.0] - 2022-12-15](#v400---2022-12-15)
   - [Added](#added-6)
   - [Changed](#changed-5)
   - [Removed](#removed-5)
   - [Fixed](#fixed-6)
-  - [Runtime Dependencies](#runtime-dependencies-2)
-- [[2.0.0] - 2022-09-12](#200---2022-09-12)
+  - [Runtime Dependencies](#runtime-dependencies-1)
+- [[3.0.0] - 2022-11-21](#300---2022-11-21)
   - [Added](#added-7)
   - [Changed](#changed-6)
   - [Removed](#removed-6)
   - [Fixed](#fixed-7)
-- [[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-8)
-  - [Removed](#removed-7)
   - [Changed](#changed-7)
+  - [Removed](#removed-7)
   - [Fixed](#fixed-8)
-- [[1.1.0] - 2022-06-30](#110---2022-06-30)
+- [[2.0.0-alpha] - 2022-07-05](#200-alpha---2022-07-05)
+  - [Added](#added-9)
+  - [Removed](#removed-8)
+  - [Changed](#changed-8)
   - [Fixed](#fixed-9)
-- [[1.0.1] - 2022-06-17](#101---2022-06-17)
+- [[1.1.0] - 2022-06-30](#110---2022-06-30)
   - [Fixed](#fixed-10)
+- [[1.0.1] - 2022-06-17](#101---2022-06-17)
+  - [Fixed](#fixed-11)
 - [[1.0.0] - 2022-06-10](#100---2022-06-10)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -66,15 +71,151 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Added
 
+### Removed
+
+### Changed
+
+### Fixed
+
+## [v8.0.0]
+
+In this version, we've refactored CTL and split it into multiple reusable sub-packages, most notably:
+
+- this package
+- `purescript-cardano-types` - (`Cardano.Types.*`) - domain types for Cardano ledger
+- `purescript-cardano-serialization-lib` - (`Cardano.Serialization.Lib.*`) - PureScript wrapper for CSL
+- `purescript-plutus-types` - (`Cardano.Plutus.*`) - Plutus-style domain types used only for `ToData`/`FromData` instances.
+
+See the [cardano-purescript repo](https://github.com/klntsky/cardano-purescript) for a complete list of new packages.
+
+These packages maintain their own public API, so the interfaces you should use are not necessarily namespaced under `Contract.*` anymore. E.g. `Cardano.Types.*` from `purescript-cardano-types` is public.
+
+Starting from this version, CTL does not use Plutus-domain types anymore. This change comes with some downsides (e.g. the need to provide NetworkId in `Address`es), but the benefit of not caring about conversions for basic functionality will hopefully be more noticeable. The only case when a conversion is needed is when the developer wants to use [`purescript-plutus-types`](https://github.com/mlabs-haskell/purescript-plutus-types), which is a package that offers `PlutusData` encodings compatible with Plutus. Its main purpose is to be used when there is a need to apply arguments to parametrized scripts.
+
+### Added
+
+- New purescript dependencies:
+  - [`purescript-bytearrays`](https://github.com/mlabs-haskell/purescript-bytearrays)
+  - [`purescript-cardano-hd-wallet`](https://github.com/mlabs-haskell/purescript-cardano-hd-wallet)
+  - [`purescript-cardano-message-signing`](https://github.com/mlabs-haskell/purescript-cardano-message-signing)
+  - [`purescript-cardano-plutus-data-schema`](https://github.com/mlabs-haskell/purescript-cardano-plutus-data-schema)
+  - [`purescript-cardano-serialization-lib`](https://github.com/mlabs-haskell/purescript-cardano-serialization-lib)
+  - [`purescript-cardano-types`](https://github.com/mlabs-haskell/purescript-cardano-types)
+- `Contract.Address.mkAddress` - a helper that automatically uses the correct `NetworkId` to construct an `Address`.
+- Sharing wallets between Plutip tests - see [the docs for this feature](./doc/plutip-testing.md#sharing-wallet-state-between-tests) ([#1585](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1585))
+  - `runPlutipTestPlan` is a new function that executes a `ContractTestPlan`.
+  - `sameWallets` is a new function that creates a `ContractTestPlan` from a `UtxoDistribution` and a `TestPlanM` of the same wallets running different `Contract`s.
+- new `onClusterStartup` hook that allows to get cluster startup parameters (private keys, `cardano-node` socket and config paths). See [`Test.Ctl.Plutip.Contract.ClusterParameters`](./test/Plutip/Contract/ClusterParameters.purs). ([#1610](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1610))
+
+
 ### Changed
 
 - Replaced custom CIP-30 wrapper code with [`purescript-cip30-typesafe`](https://github.com/mlabs-haskell/purescript-cip30-typesafe/) - ([#1583](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1583))
+- Renamings for better conformity with CSL:
+  - `TokenName` renamed to `AssetName`
+  - `NonAdaAsset` renamed to `MultiAsset`
+  - `CurrencySymbol` renamed to `ScriptHash`
+- `Coin` now wraps BigNum instead of BigInt (in line with CSL)
+- `NoOutputDatum` variant has been removed from `OutputDatum`: instead, it was made optional via `Maybe` in `TransactionOutput`
+- `TransactionMetadatum` constructor naming change, in PS and in JSON encoding: `MetadataMap` -> `Map`, `MetadataList` -> `List`
+- `Contract.PlutusData.Redeemer` has been renamed to `RedeemerDatum` (to resolve naming conflict with `cardano-ledger`-style redeemer)
+- `Contract.PlutusData.Datum` has been deprecated, use `Cardano.Types.PlutusData`
+- `plutusScriptV1FromEnvelope`, `plutusScriptV2FromEnvelope` have been replaced with `plutusScriptFromEnvelope` (the script is tagged with its language anyway)
 
 ### Fixed
+- Plutip cluster's Kupo instances don't share the same working folder anymore - ([#1570](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1570))
+- WebAssembly memory leaks (`csl-gc-wrapper` used to depend on unstable `wasm-bidngen` API [that got changed](https://github.com/mlabs-haskell/csl-gc-wrapper/commit/2dea38228b77f7c904aafef12eece7e5af195977)) ([#1595](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1595))
 
 ### Removed
 
+- **[IMPORTANT]** Removed use of conditional code rewriting based on `BROWSER_RUNTIME` env variable during bundling ([#1595](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1598)). This change simplifies the bundling process, but it requires a number of updates for all CTL-dependent projects:
+
+   * WebPack users should make this change to the webpack config:
+   ```diff
+       plugins: [
+   -      new webpack.DefinePlugin({
+   -        BROWSER_RUNTIME: isBrowser
+   -      }),
+   ```
+   * Esbuild users should make this change:
+   ```diff
+   const config = {
+     ...
+   -    define: {
+   -      BROWSER_RUNTIME: isBrowser ? "true" : '""'
+   -    },
+   ```
+   * All users should update the runtime dependencies:
+   ```diff
+   -    "@emurgo/cardano-message-signing-browser": "1.0.1",
+   -    "@emurgo/cardano-message-signing-nodejs": "1.0.1",
+   +    "@mlabs-haskell/cardano-message-signing": "1.0.1",
+   -    "apply-args-browser": "0.0.1",
+   -    "apply-args-nodejs": "0.0.1",
+   +    "@mlabs-haskell/uplc-apply-args": "1.0.0",
+   +    "isomorphic-ws": "^5.0.0",
+   -    "ws": "8.4.0",
+   +    "ws": "^8.16.0",
+   +    "web-encoding": "^1.1.5",
+   ```
+- NPM runtime dependencies:
+
+```diff
+     "bip39": "^3.1.0",
+-    "blakejs": "1.2.1",
+     "bufferutil": "4.0.5",
+-    "jssha": "3.2.0",
+     "puppeteer-core": "^15.3.2",
+     "reconnecting-webs
+```
+
+- `Contract.Address` utilities to work with `Address` - use `mkAddress` and machinery from `Cardano.Types.Address`
+- `Contract.RewardAddress` - use `Cardano.Types.RewardAddress`
+- `Contract.Transaction`:
+  - Removed newtypes for `Transaction`:
+     - `BalancedSignedTransaction`
+     - `FinalizedTransaction`
+- `Contract.Scripts`:
+  - `MintingPolicy` type. It was not used anywhere except of `mintingPolicy` lookup. Use `plutusMintingPolicy` and `nativeMintingPolicy` lookups instead.
+- `Contract.ScriptLookups`:
+  - synonyms for lookup functions that use `Maybe` have been removed: `mintingPolicyM`, `ownPaymentPubKeyHashM`, `ownStakePubKeyHashM`, `unspentOutputsM`, `validatorM`
+- `Contract.Credential` renamings:
+  - `PubKeyCredential` -> `PubKeyHashCredential`
+  - `ScriptCredential` -> `ScriptHashCredential`
 - `ModifyTx` error: made conversion functions total and removed the need to handle it
+- `Contract.CborBytes` utils:
+  - `cborBytesToByteArray`
+  - `cborBytesFromByteArray`
+  - `cborBytesFromAscii`
+  - `cborBytesToIntArray`
+  - `cborBytesFromIntArray`
+  - `cborBytesFromIntArrayUnsafe`
+  - `cborBytesToHex`
+  - `cborByteLength`
+  - `hexToCborBytes`
+  - `hexToCborBytesUnsafe`
+  - `rawBytesAsCborBytes`
+- `ToData`/`FromData` Instances for `purescript-noble-secp256k1` types (PS does not allow orphans)
+- `ToMetadata`/`FromMetadata` instance for `BigInt`: it was partial and unsafe
+- `Cardano.Types.BigNum.toInt'` method
+- `Contract.Address`:
+   - `scriptHashAddress` - use `Contract.Address.mkAddress`
+   - `payPubKeyHashBaseAddress` - use `Contract.Address.mkAddress`
+   - `payPubKeyHashEnterpriseAddress` - use `Contract.Address.mkAddress`
+- `Contract.Value`:
+   - `flattenNonAdaAssets` - use `Cardano.Types.Value.flatten`.
+- `Contract.PlutusData`:
+   - `Datum`: removed, use `Cardano.Types.PlutusData`
+   - `unitDatum`
+- `Contract.TextEnvelope`:
+   - `plutusScriptV1FromEnvelope` - use `plutusScriptFromEnvelope`
+- `Contract.Hashing`
+- `Contract.Transaction`:
+   - `TransactionOutputWithRefScript` - use `Cardano.Types.TransactionOutput`. It comes with refscript included.
+   - `getTxFinalFee`
+- `Contract.Numeric.NatRatio` - the module was not used in the library.
+- `Contract.AssocMap` - use `Cardano.Plutus.Types.Map` from [`purescript-plutus-types`](https://github.com/mlabs-haskell/purescript-plutus-types)
+- CIP-25 metadata machinery (we need to keep the API surface thin for CTL)
 
 ## [v7.0.0]
 

Makefile

@@ -13,7 +13,8 @@ js-sources := $(shell fd --no-ignore-parent -ejs -ecjs)
 ps-entrypoint := Ctl.Examples.ByUrl
 # The entry point function in the main PureScript module
 ps-entrypoint-function := main
-# Whether to bundle for the browser
+# Whether to bundle for the browser ("1") or the node ("")
+# NOTE: bundling for the node is not necessary, see https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/doc/using-from-js.md
 browser-runtime := 1 # Use "1" for true and "" for false
 
 preview-node-ipc = $(shell docker volume inspect store_node-preview-ipc | jq -r '.[0].Mountpoint')
@@ -61,6 +62,7 @@ webpack-serve: spago-build create-bundle-entrypoint create-html-entrypoint
 check-explicit-exports:
 	@if grep -rn '(\.\.)' ${ps-sources}; then
 		echo "Use explicit imports/exports ^"
+		echo "Run ./scripts/import-fixer.sh to autofix some of these"
 		exit 1
 	else
 		echo "All imports/exports are explicit"

README.md

@@ -1,4 +1,5 @@
-# cardano-transaction-lib
+# cardano-transaction-lib [![cardano-purescript](https://img.shields.io/badge/cardano--purescript?logo=cardano&logoColor=white&label=cardano-purescript&labelColor=blue&color=blue)](https://github.com/klntsky/cardano-purescript)
+
 
 [![Hercules-ci][herc badge]][herc link]
 [![Cachix Cache][cachix badge]][cachix link]
@@ -11,17 +12,14 @@
 [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 and NodeJS.
+**cardano-transaction-lib** (CTL) is a Purescript framework for building smart contract transactions on Cardano. It belongs to the the same category of tools as Lucid, Mesh.js, Atlas, Plutus Application Backend (PAB).
 
 **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 -->
 
 - [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)
 - [Funding acknowledgements](#funding-acknowledgements)
@@ -31,7 +29,7 @@
 
 ## Documentation
 
-Please explore our documentation to discover how to use CTL, how to set up its runtime, and how it compares to Plutus/PAB:
+Please explore our documentation to discover how to use CTL, how to set up its runtime, and how it compares to other tools:
 
 - [Super quick start](./doc/getting-started.md#setting-up-a-new-project)
 - [Adding CTL as a dependency](./doc/ctl-as-dependency.md)
@@ -41,65 +39,26 @@ Please explore our documentation to discover how to use CTL, how to set up its r
 - [Managing contract environment](./doc/contract-environment.md)
 - [Using CTL from JS](./doc/using-from-js.md)
 - [Importing Plutus Scripts](./doc/importing-scripts.md)
-- [Migrating from Plutus to CTL](./doc/plutus-comparison.md)
+- [Migrating from Plutus Application Backend to CTL](./doc/plutus-comparison.md)
 - [Overview of testing approaches](./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)
+  - [Testing on local testnets with Plutip](./doc/plutip-testing.md)
+  - [End-to-end dApp testing with headless browsers](./doc/e2e-testing.md)
+  - [Assertion utilities for testing](./doc/test-utils.md)
+  - [Using a directory with private keys to run tests](./doc/keydir.md)
 - [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)
+- [Going to production with CTL](./doc/production.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).
 
-### Light wallet support
-
-Support is planned for the following light wallets:
-
-- [x] [Nami](https://namiwallet.io/)
-- [x] [Gero](https://gerowallet.io/)
-- [x] [Flint](https://flint-wallet.com/)
-- [x] [Lode](https://lodewallet.io/)
-- [x] [Eternl (formerly CCvault)](https://eternl.io/)
-- [x] [NuFi](https://nu.fi/)
-- [x] [Lace](https://www.lace.io/)
-- [ ] [Typhon](https://typhonwallet.io/)
-- [ ] [Yoroi](https://yoroi-wallet.com/)
-
-## Roadmap
-
-- [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
-- [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
-
-CTL is directly inspired by the Plutus Application Backend (PAB). Unlike PAB, however, CTL is a library and not a standalone process. Over the course of CTL's development, several questions have been raised as to how best create PAB-as-a-library:
-
-1. How do we get the transaction in the right format?
-   - 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
-   - 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
-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
-
 ## Additional resources/tools:
 
 - [`cardano-serialization-lib`](https://github.com/Emurgo/cardano-serialization-lib/)

doc/blockfrost.md

@@ -210,4 +210,5 @@ This function is never used for constraints resolution, the only way to make it
 
 ## See also
 
+- [key-directory test suite](./keydir.md) that is used under the hood by `executeContractTestsWithBlockfrost`. This test machinery can be used with any runtime backend, not just Blockfrost.
 - [Testing utilities for CTL](./test-utils.md).