Mm/effectful

README.md

@@ -1,58 +1,46 @@
 # [Cooked Validators](https://github.com/tweag/cooked-validators/)
 
-Copyright Tweag I/O 2026
-
-`cooked-validators` is a Haskell library for writing reliable, concise, and
-expressive off-chain code for Cardano smart contracts, with a primary focus on
-testing, auditing, and behavioral exploration.
-
-It allows you to describe transactions at a high level (via what we call
-transaction skeletons) and automatically turn them into complete, valid
-transactions by handling all mechanical aspects such UTxO selection, balancing,
-minimum-Ada constraints, collaterals or fees.
-
-The library is designed to:
-- drastically reduce off-chain boilerplate,
-- make test scenarios more readable and maintainable,
-- facilitate adversarial testing and vulnerability discovery.
-
-Importantly, `cooked-validators` is non-opinionated: everything it automates can
-also be done manually if needed, allowing users to retain full control over
-transaction construction when desired.
-
-## Core features
-
-With `cooked-validators`, you can:
-- Interact with smart contracts written in Plutus or any language that compiles
-to [UPLC](https://plutonomicon.github.io/plutonomicon/uplc), such as
-[Plutarch](https://github.com/Plutonomicon/plutarch-plutus) or
-[Aiken](https://aiken-lang.org/), by loading contracts from bytestrings.
-- Define transactions using a high-level, type-preserving data structure.
-- Submit transactions for validation while the library automatically:
-    * fills in missing inputs and outputs,
-    * performs balancing,
-    * enforces minimum-Ada constraints,
-    * computes and attaches optimal collaterals and fees,
-	* automatically adds script witnesses, including from reference inputs.
-- Construct sequences of transactions in a clear, implementation-independent
-  abstraction of the blockchain.
-- Run transaction sequences in an emulated blockchain.
-- Define modifications aware of the current blockchain state (tweaks), and apply
-  them to transactions just before submission.
-- Compose and deploy tweaks on sequences of transactions using idioms inspired
-  by linear temporal logic.
-- Deploy automated attacks on existing transaction sequences, such as datum
-  hijacking or double satisfaction attacks, to uncover vulnerabilities.
-- Express expected outcomes on the result of running a trace in a precise and
-  declarative way, for example by:
-    * specifying the expected number of outcomes in case branching occurred,
-    * asserting exact error messages in case of failure,
-	* ensuring a specific event was triggered during the run,
-    * checking that some specific assets are present at a given address in the
-      final blockchain state.
+Copyright Tweag I/O 2025
+
+`cooked-validators` is a Haskell library to conveniently and efficiently write
+off-chain code for Cardano smart contracts. This offchain code will be
+specifically geared to testing and auditing the smart contract in question with
+further builtin capabilities of the library.
+
+In particular, `cooked-validators` allows the user to:
+- interact with smart contracts written in Plutus or any other language that
+  compiles to [UPLC](https://plutonomicon.github.io/plutonomicon/uplc), like for
+  example [Plutarch](https://github.com/Plutonomicon/plutarch-plutus) or
+  [Aiken](https://aiken-lang.org/), by loading contracts from byte strings
+- define transactions in a high level, type-retaining data structure
+- submit transactions for validation, while automatically taking care of missing
+  inputs and outputs, balancing, minimum-Ada constraints, collaterals and fees
+- construct sequences of transactions in an easy-to-understand abstraction of
+  "the blockchain", which can be instantiated to different actual
+  implementations
+- run sequences of transactions in a simulated blockchain
+- apply "tweaks" to transactions right before submitting them, where "tweaks"
+  are modifications that are aware of the current state of the simulated
+  blockchain
+- compose and deploy tweaks with flexible idioms inspired by linear temporal
+  logic, in order to turn one sequence of transactions into many sequences that
+  might be useful test cases, generalized in
+  [Graft](https://github.com/tweag/graft)
+- deploy automated attacks over existing sequences of transactions, such as
+  datum hijacking or double satisfaction attacks, in an attempt to uncover
+  vulnerabilities
+
+You are free to copy, modify, and distribute `cooked-validators` under the terms
+of the MIT license. We provide `cooked-validators` as a research prototype under
+active development, and it comes _as is_ with no guarantees whatsoever. Check
+the [license](LICENSE) for details.
 
 ## How to integrate `cooked-validators` in a project
 
+To use `cooked-validators`, you need
+- [GHC](https://www.haskell.org/ghc/download_ghc_9_6_6.html) version 9.6.6
+- [Cabal](https://www.haskell.org/cabal) version 3.10 or later
+
 1. `cooked-validators` depends on
 [cardano-haskell-packages](https://github.com/input-output-hk/cardano-haskell-packages)
 to get cardano-related packages and on
@@ -71,84 +59,40 @@ the `packages` stanza.
      subdir:
        .
    ```
-   where `myTag` is either a commit hash in the repo, or a tag, such as v8.0.0
+   where `myTag` is either a commit hash in the repo, or a tag, such as v7.0.0
    (see [available
    releases](https://github.com/tweag/cooked-validators/releases)).
 
-3. Each release of `cooked-validators` is pinned to a specific version of
-   [`cardano-api`](https://github.com/IntersectMBO/cardano-api) which in turn
-   pins the versions of all other Cardano-related dependencies (including
-   Plutus). Make sure your project relies on the same version.
-
 ## Example
 
-This example shows how to create and validate a simple transaction that
-transfers 10 Ada from wallet 1 to wallet 2, without manually handling fees or
-balancing.
-
-1. Enter a Cabal read-eval-print-loop (with `cabal repl`)
-
-2. Import your required dependencies
-   ``` haskell
+1. Make your project
+   [depend](https://cabal.readthedocs.io/en/stable/getting-started.html#adding-dependencies)
+   on `cooked-validators` and `plutus-script-utils`
+   
+2. Enter a Cabal read-eval-print-loop (with `cabal repl`)
+   and create and validate a transaction which transfers 10 Ada
+   from wallet 1 to wallet 2:
+   ```haskell
    > import Cooked
    > import qualified Plutus.Script.Utils.Value as Script
-   ```
-
-3. Define a transaction which transfers 10 Ada from wallet 1 to wallet 2
-   ``` haskell
-   let myTransaction = txSkelTemplate {txSkelOuts = [wallet 2 `receives` Value (Script.ada 10)], txSkelSignatories = txSkelSignatoriesFromList [wallet 1]}
-   ```
-
-4. Send the transaction for validation, and request the printing of the run
-   ``` haskell
-   printCooked . runMockChain . validateTxSkel_ $ myTransaction 
-   ```
-
-5. Observe the log of the run, including:
-    - The original skeleton, and its balanced counterpart
-	- The associated fee and collaterals
-	- The final mockchain state, with every wallet's assets (notice the 10 ADA
-      payment owned by wallet 2)
-	- The value returned by the run (here `()` as we used `validateTxSkel_`)
-   ```haskell
-   📖 MockChain run log:
-	 ⁍ New raw skeleton submitted to the adjustment pipeline:
-	   - Validity interval: (-∞ , +∞)
-	   - Signatories:
-		 - wallet 1 [balancing]
-	   - Outputs:
-		 - Pays to pubkey wallet 2
-		   - Lovelace: 10_000_000
-	 ⁍ New adjusted skeleton submitted for validation:
-	   - Validity interval: (-∞ , +∞)
-	   - Signatories:
-		 - wallet 1 [balancing]
-	   - Inputs:
-		 - Spends #4480b35!3 from pubkey wallet 1
-		   - Redeemer ()
-		   - Lovelace: 100_000_000
-	   - Outputs:
-		 - Pays to pubkey wallet 2
-		   - Lovelace: 10_000_000
-		 - Pays to pubkey wallet 1
-		   - Lovelace: 89_828_383
-	   - Fee: Lovelace: 171_617
-	   - No collateral required
-	 ⁍ New transaction successfully validated:
-	   - Transaction id: #c095342
-	   - Number of new outputs: 2
-   ✅ UTxO state:
-	 • pubkey wallet 1
-	   - Lovelace: 89_828_383
-	   - (×3) Lovelace: 100_000_000
-	 • pubkey wallet 2
-	   - Lovelace: 10_000_000
-	   - (×4) Lovelace: 100_000_000
-	 • pubkey wallet 3
-	   - (×4) Lovelace: 100_000_000
-	 • pubkey wallet 4
-	   - (×4) Lovelace: 100_000_000
-   🟢 Returned value: () 
+   > printCooked . runMockChain . validateTxSkel $
+         txSkelTemplate
+           { txSkelOuts = [wallet 2 `receives` Value (Script.ada 10)],
+             txSkelSigners = [wallet 1]
+           }
+   [...]
+   - UTxO state:
+     • pubkey wallet 1
+       - Lovelace: 89_828_471
+       - (×4) Lovelace: 100_000_000
+     • pubkey wallet 2
+       - Lovelace: 10_000_000
+       - (×5) Lovelace: 100_000_000
+     • pubkey wallet 3
+       - (×5) Lovelace: 100_000_000
+     • pubkey wallet 4
+       - (×5) Lovelace: 100_000_000
+   [...]
    ```
 
 ## Documentation
@@ -171,32 +115,6 @@ balancing.
 - The [OPTICS](doc/OPTICS.md) file describes our usage of optics to navigate our
   data structures.
 
-## Blog posts
-
-Several blog posts have been written about `cooked-validators`. As the library
-evolves, some code snippets in these posts may have become outdated. However,
-the core philosophy remains unchanged, and these articles still provide valuable
-insight into how to use the library.
-
-1. [An article](https://www.tweag.io/blog/2023-05-11-audit-smart-contract/)
-   explaining how we use `cooked-validators` to conduct smart contract audits.
-
-2. [An
-   article](https://www.tweag.io/blog/2025-02-20-transaction-generation-automation-with-cooked-validators/)
-   describing how transaction skeletons are built in `cooked-validators` and how
-   the library constructs complete transactions from them.
-
-3. [An
-   article](https://www.tweag.io/blog/2022-01-26-property-based-testing-of-monadic-code/)
-   presenting the original idea of using temporal modalities to modify sequences
-   of transactions.
-
-
-4. [An article](https://www.tweag.io/blog/2022-10-14-ltl-attacks/) explaining
-   how [linear temporal
-   logic](https://en.wikipedia.org/wiki/Linear_temporal_logic) is used in
-   `cooked-validators` to deploy modifications over time.
-
 ## Additional resources
 
 - We have a [repository](https://github.com/tweag/cooked-smart-contracts) of
@@ -217,10 +135,3 @@ insight into how to use the library.
 - `cooked-validators` comes with a [template
   repository](https://github.com/tweag/cooked-template) which can be used to
   develop offchain code and/or audit code with the tool.
-
-## License
-
-You are free to copy, modify, and distribute `cooked-validators` under the terms
-of the MIT license. We provide `cooked-validators` as a research prototype under
-active development, and it comes _as is_ with no guarantees whatsoever. Check
-the [license](LICENSE) for details.

cabal.project

@@ -46,8 +46,11 @@ package cardano-crypto-praos
   flags: -external-libsodium-vrf
 
 constraints:
-  cardano-api == 10.18.1.0
-
+  , cardano-api == 10.18.1.0
+  , plutus-ledger-api == 1.45.0.0
+  , polysemy == 1.9.2.0
+  , polysemy-plugin == 0.4.5.3
+
 source-repository-package
     type: git
     location: https://github.com/intersectMBO/cardano-node-emulator

cooked-validators.cabal

@@ -1,11 +1,11 @@
 cabal-version: 3.4
 
--- This file has been generated from package.yaml by hpack version 0.38.2.
+-- This file has been generated from package.yaml by hpack version 0.38.3.
 --
 -- see: https://github.com/sol/hpack
 
 name:           cooked-validators
-version:        8.0.0
+version:        7.0.0
 license:        MIT
 license-file:   LICENSE
 build-type:     Simple
@@ -17,30 +17,37 @@ library
       Cooked.Attack.AddToken
       Cooked.Attack.DatumHijacking
       Cooked.Attack.DoubleSat
+      Cooked.Families
       Cooked.InitialDistribution
       Cooked.Ltl
       Cooked.MockChain
       Cooked.MockChain.AutoFilling
       Cooked.MockChain.Balancing
-      Cooked.MockChain.BlockChain
-      Cooked.MockChain.Direct
+      Cooked.MockChain.Common
+      Cooked.MockChain.Error
       Cooked.MockChain.GenerateTx.Anchor
       Cooked.MockChain.GenerateTx.Body
       Cooked.MockChain.GenerateTx.Certificate
       Cooked.MockChain.GenerateTx.Collateral
-      Cooked.MockChain.GenerateTx.Common
+      Cooked.MockChain.GenerateTx.Credential
       Cooked.MockChain.GenerateTx.Input
       Cooked.MockChain.GenerateTx.Mint
       Cooked.MockChain.GenerateTx.Output
       Cooked.MockChain.GenerateTx.Proposal
       Cooked.MockChain.GenerateTx.ReferenceInputs
       Cooked.MockChain.GenerateTx.Withdrawals
       Cooked.MockChain.GenerateTx.Witness
-      Cooked.MockChain.MockChainState
-      Cooked.MockChain.Staged
+      Cooked.MockChain.Instances
+      Cooked.MockChain.Journal
+      Cooked.MockChain.Log
+      Cooked.MockChain.Misc
+      Cooked.MockChain.Read
+      Cooked.MockChain.Runnable
+      Cooked.MockChain.State
       Cooked.MockChain.Testing
+      Cooked.MockChain.Tweak
       Cooked.MockChain.UtxoSearch
-      Cooked.MockChain.UtxoState
+      Cooked.MockChain.Write
       Cooked.Pretty
       Cooked.Pretty.Class
       Cooked.Pretty.Hashable
@@ -53,7 +60,6 @@ library
       Cooked.Skeleton.Anchor
       Cooked.Skeleton.Certificate
       Cooked.Skeleton.Datum
-      Cooked.Skeleton.Families
       Cooked.Skeleton.Label
       Cooked.Skeleton.Mint
       Cooked.Skeleton.Option
@@ -64,7 +70,6 @@ library
       Cooked.Skeleton.User
       Cooked.Skeleton.Value
       Cooked.Skeleton.Withdrawal
-      Cooked.Staged
       Cooked.Tweak
       Cooked.Tweak.Common
       Cooked.Tweak.Inputs
@@ -109,7 +114,7 @@ library
       TypeFamilies
       TypeOperators
       ViewPatterns
-  ghc-options: -Wall -Wcompat -Wincomplete-record-updates -Wincomplete-uni-patterns -Wredundant-constraints -Wno-missed-extra-shared-lib -fobject-code -fno-ignore-interface-pragmas -fignore-hpc-changes -fno-omit-interface-pragmas -fplugin-opt PlutusTx.Plugin:defer-errors -fplugin-opt PlutusTx.Plugin:conservative-optimisation
+  ghc-options: -Wall -Wcompat -Wincomplete-record-updates -Wincomplete-uni-patterns -Wredundant-constraints -Wno-missed-extra-shared-lib -fobject-code -fno-ignore-interface-pragmas -fignore-hpc-changes -fno-omit-interface-pragmas -fplugin-opt PlutusTx.Plugin:defer-errors -fplugin-opt PlutusTx.Plugin:conservative-optimisation -fplugin=Polysemy.Plugin
   build-depends:
       QuickCheck
     , base >=4.9 && <5
@@ -143,6 +148,8 @@ library
     , plutus-script-utils
     , plutus-tx
     , plutus-tx-plugin
+    , polysemy
+    , polysemy-plugin
     , prettyprinter
     , random
     , random-shuffle
@@ -183,6 +190,7 @@ test-suite spec
       Spec.ReferenceInputs
       Spec.ReferenceScripts
       Spec.Slot
+      Spec.StagedRun
       Spec.Tweak
       Spec.Tweak.Common
       Spec.Tweak.Labels
@@ -223,7 +231,7 @@ test-suite spec
       TypeFamilies
       TypeOperators
       ViewPatterns
-  ghc-options: -Wall -Wcompat -Wincomplete-record-updates -Wincomplete-uni-patterns -Wredundant-constraints -Wno-missed-extra-shared-lib -fobject-code -fno-ignore-interface-pragmas -fignore-hpc-changes -fno-omit-interface-pragmas -fplugin-opt PlutusTx.Plugin:defer-errors -fplugin-opt PlutusTx.Plugin:conservative-optimisation
+  ghc-options: -Wall -Wcompat -Wincomplete-record-updates -Wincomplete-uni-patterns -Wredundant-constraints -Wno-missed-extra-shared-lib -fobject-code -fno-ignore-interface-pragmas -fignore-hpc-changes -fno-omit-interface-pragmas -fplugin-opt PlutusTx.Plugin:defer-errors -fplugin-opt PlutusTx.Plugin:conservative-optimisation -fplugin=Polysemy.Plugin
   build-depends:
       QuickCheck
     , base >=4.9 && <5
@@ -258,6 +266,8 @@ test-suite spec
     , plutus-script-utils
     , plutus-tx
     , plutus-tx-plugin
+    , polysemy
+    , polysemy-plugin
     , prettyprinter
     , random
     , random-shuffle