diff --git a/README.md b/README.md index f92237a3a..1c4468c84 100644 --- a/README.md +++ b/README.md @@ -2,69 +2,82 @@ Copyright Tweag I/O 2024 -With `cooked-validators` you can test Cardano smart contracts by writing potentially malicious offchain code. -You can also use the library to write "normal" offchain code in a comfortable and flexible way. +`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` helps you: -- interact with smart contracts written in Plutus (as well as any other language +In particular, `cooked-validators` allows 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) -- generate and submit transactions declaratively, while automatically taking - care of missing inputs and outputs, balancing, and minimum-Ada constraints -- 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) + or [Aiken](https://aiken-lang.org/), by loading contracts from byte strings. +- declaratively define transactions in a high level, type-retaining + data structure, and submitting them 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 -The library is geared specifically towards testing and auditing on-chain code. - -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. +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 -This guide shows you how to use `cooked-validators` in a haskell project -using [Cabal](https://cabal.readthedocs.io/en/stable/) -to create and validate a simple transaction. - -Before using `cooked-validators`, you need -- [GHC](https://www.haskell.org/ghc/download_ghc_8_10_7.html) version 8.10.7 -- [Cabal](https://www.haskell.org/cabal) +To use `cooked-validators`, you need +- [GHC](https://www.haskell.org/ghc/download_ghc_9_6_5.html) version 9.6.5 +- [Cabal](https://www.haskell.org/cabal) version 3.10 or later -1. If you have no constraint on the version of `plutus-apps`, copy the file - [`cabal.project`](./cabal.project) to your project and - [adapt](https://cabal.readthedocs.io/en/stable/cabal-project.html#specifying-the-local-packages) - the `packages` stanza. +1. `cooked-validators` depends on +[cardano-haskell-packages](https://github.com/input-output-hk/cardano-haskell-packages) +to get cardano-related packages and on +[cardano-node-emulator](https://github.com/IntersectMBO/cardano-node-emulator) +directly. If you have no constraint on the version of this package, +copy the file [`cabal.project`](./cabal.project) to your project and +[adapt](https://cabal.readthedocs.io/en/stable/cabal-project.html#specifying-the-local-packages) +the `packages` stanza. + 2. Add the following stanza to the file `cabal.project` ```cabal.project source-repository-package type: git location: https://github.com/tweag/cooked-validators - tag: v3.0.0 + tag: myTag subdir: - cooked-validators + . ``` -3. Make your project + where `myTag` is either a commit hash in the repo, or a tag, such as v4.0.0 + +## An example of usage of `cooked-validators` + +1. Make your project [depend](https://cabal.readthedocs.io/en/stable/getting-started.html#adding-dependencies) on `cooked-validators` and `plutus-script-utils` + 3. 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.Ada as Pl + > import qualified Plutus.Script.Utils.Ada as Script > printCooked . runMockChain . validateTxSkel $ txSkelTemplate - { txSkelOuts = [paysPK (walletPKHash $ wallet 2) (Pl.adaValueOf 10)], + { txSkelOuts = [paysPK (wallet 2) (Script.adaValueOf 10)], txSkelSigners = [wallet 1] } [...] @@ -84,17 +97,25 @@ Before using `cooked-validators`, you need ## Documentation -The rendered Haddock for the current `main` branch can be found at +- The rendered Haddock for the current `main` branch can be found at [https://tweag.github.io/cooked-validators/](https://tweag.github.io/cooked-validators/). -The [CHEATSHEET](doc/CHEATSHEET.md) is a nice entry point and helper to keep on -sight. It contains many code snippets to quickly get an intuition of how to do -things. Use it to discover or search for how to use features of -`cooked-validators`. Note that this is not a tutorial nor a ready-to-use -recipes book. +- The [CHEATSHEET](doc/CHEATSHEET.md) is a nice entry point and helper +to keep on sight. It contains many code snippets to quickly get an +intuition of how to do things. Use it to discover or search for how to +use features of `cooked-validators`. Note that this is not a tutorial +nor a ready-to-use recipes book. + +- The [IMPORTS](doc.IMPORTS.md) file is a nice source of information + to understand the dependencies we use and how we name them. -We also have a [repository](https://github.com/tweag/cooked-smart-contracts) of example contracts with offchain code and tests written using `cooked-validators`. +- We also have a +[repository](https://github.com/tweag/cooked-smart-contracts) of +example contracts with offchain code and tests written using +`cooked-validators`. Note that these examples are not maintained and +thus written with various versions of the tool. -Please also look at our -[issues](https://github.com/tweag/cooked-validators/issues) for problems that -we're already aware of, and feel free to open new issues! +- Please also look at our +[issues](https://github.com/tweag/cooked-validators/issues) for +problems that we're already aware of, and feel free to open new +issues!