Tutorial

README.md

@@ -0,0 +1,71 @@
+# Yielding Transaction Pattern Library (ytxp-lib)
+
+The YTxP is a flexible and secure architectural approach for modeling Cardano protocols using transaction families.
+
+* [Understand the core concepts of YTxP](/docs/README.md)
+* [How to write a YTxP specification](/ytxp-plutarch/examples/direct-offer/doc/tutorials/specification.md)
+* How to set up and configure the `ytxp-lib` and implement a basic protocol using the YTxP.
+
+## Tooling
+
+### Continuous Integration (CI)
+The CI for this project runs using [Hercules CI](https://hercules-ci.com). All the pre-commit checks will run in CI.
+
+### Developer Experience (DevEx)
+All the commands used for development purposes are exposed through the [Makefile](./Makefile). To see the available commands, you can simply run:
+
+```bash
+make
+```
+
+### Formatting
+The format of most of the source files is checked. You can use individual commands through the `Makefile` or you can simply run:
+
+```bash
+make format_lint
+```
+
+to apply all the linters and formatters. This might be useful.
+
+**Note:** Some linters cannot automatically fix your code. For example, `markdownlint` may signal that a code block (delimited by ```) does not have the language specified but cannot automatically infer the language of the code. This means that in general, `make format_lint` does not resolve all the problems that pre-commit checks can raise.
+
+### Haddock Documentation
+
+The current Haddock documentation is available [here](https://mlabs-haskell.github.io/ytxp-lib/). Below are instructions for generating local Haddock documentation using various methods:
+
+#### Build
+
+##### Using Make Target
+To build documentation directly, utilize the following make target:
+
+```bash
+make build_docs
+```
+
+After the execution, this command will specify the location of the generated documentation.
+
+##### Using Nix
+
+If you are using nix, the documentation for `ytxp-plutarch library` , generating documentation can be achieved by running:
+
+```bash
+nix build .#ytxp-plutarch-lib.doc
+```
+
+#### Serve documentation locally
+
+To serve the documentation locally, utilize the following make target:
+
+```bash
+make serve_docs
+```
+
+The resulting documentation will be accessible within the `result-doc` directory.
+
+## Tests
+Tests will run in CI thanks to some specific checks in the Nix flake.
+
+You can run tests:
+
+* Using Nix: `nix flake check`: this will run all the checks, not only the tests;
+* Using Cabal directly (assuming it is present in the `$PATH`). See the `Makefile` targets to check the available test suites.

docs/README.md

@@ -1,4 +1,4 @@
-# Yielding Transaction Pattern Library (ytxp-lib)
+# Yielding Transaction Pattern (YTxP)
 
 The Yielding Transaction Pattern is pretty simple.
 
@@ -104,67 +104,3 @@ Transaction families are implemented as `AuthorisedScripts`. These can be:
 
 See [this](https://github.com/Anastasia-Labs/design-patterns/blob/main/stake-validator/STAKE-VALIDATOR-TRICK.md) for more details on the idea and execution of the
 “withdraw 0”
-
-## Tooling
-
-### Continuous Integration (CI)
-The CI for this project runs using [Hercules CI](https://hercules-ci.com). All the pre-commit checks will run in CI.
-
-### Developer Experience (DevEx)
-All the commands used for development purposes are exposed through the [Makefile](./Makefile). To see the available commands, you can simply run:
-
-```bash
-make
-```
-
-### Formatting
-The format of most of the source files is checked. You can use individual commands through the `Makefile` or you can simply run:
-
-```bash
-make format_lint
-```
-
-to apply all the linters and formatters. This might be useful.
-
-**Note:** Some linters cannot automatically fix your code. For example, `markdownlint` may signal that a code block (delimited by ```) does not have the language specified but cannot automatically infer the language of the code. This means that in general, `make format_lint` does not resolve all the problems that pre-commit checks can raise.
-
-### Haddock Documentation
-
-The current Haddock documentation is available [here](https://mlabs-haskell.github.io/ytxp-lib/). Below are instructions for generating local Haddock documentation using various methods:
-
-#### Build
-
-##### Using Make Target
-To build documentation directly, utilize the following make target:
-
-```bash
-make build_docs
-```
-
-After the execution, this command will specify the location of the generated documentation.
-
-##### Using Nix
-
-If you are using nix, the documentation for `ytxp-plutarch library` , generating documentation can be achieved by running:
-
-```bash
-nix build .#ytxp-plutarch-lib.doc
-```
-
-#### Serve documentation locally
-
-To serve the documentation locally, utilize the following make target:
-
-```bash
-make serve_docs
-```
-
-The resulting documentation will be accessible within the `result-doc` directory.
-
-## Tests
-Tests will run in CI thanks to some specific checks in the Nix flake.
-
-You can run tests:
-
-- Using Nix: `nix flake check`: this will run all the checks, not only the tests;
-- Using Cabal directly (assuming it is present in the `$PATH`). See the `Makefile` targets to check the available test suites.

ytxp-plutarch/examples/direct-offer/doc/tutorials/specification.md

@@ -0,0 +1,60 @@
+# How to write a YTxP specification
+
+In this tutorial, we learn how to specify a specification for a direct-offer contract.
+
+Prerequisites:
+
+- Understanding of Cardano's EUTxO model and smart contract architecture.
+- [A solid understanding of the core concepts of the YTxP.](/docs/README.md)
+
+## What is the direct offer contract?
+
+The direct offer is a simple contract that enables peer-to-peer trading. Users can create an offer order by specifying the return and assigning a value as the exchange without needing a trusted third party. The offer owner can revoke its offer order at any time. Anyone can execute the offer order if the order's conditions are fulfilled.
+
+## How to write the direct offer specification
+
+The specification generally includes one component specification if using the component model, along with one or more transaction family specifications. Additionally, it may contain one or more transaction flow specifications for more complex cases.
+
+### Component
+
+For this contract, we will utilize the component model. In this model, an offer order is represented by a UTxO that includes a datum detailing the offer's specifics, and a state thread token verifies the semantic validity of the offer UTxO.
+
+For the specification, we will detail the existence of a component and describe all its attributes, including the UTxO's address, value, datum, and reference script.
+
+Specifically, we will define the attributes of the offer component in the following way:
+
+- We will not specify any particular values, as the component's value is what the consumer can keep.
+- The address must be a YTxP yielding-validator address to ensure that the yielding validator will only validate when an authorized transaction family is also validated.
+- The datum consists of two fields: the "owner" and the "to buy" value.
+- No scripts are allowed to be referenced.
+
+If a component has multiple states, we will specify that in the documentation. However, the offer component has no meaningful states, so we will not provide any details.
+
+Finally, we will specify which transaction family will introduce, modify, and terminate this component. Have a look the example of the [offer component specification](/ytxp-plutarch/examples/direct-offer/doc/components/offer.md) for more details.
+
+The component specification does not detail the transaction validation for the offer component. Validation of the component is delegated to the authorised transaction families.
+
+### Transaction families
+To determine the transaction families involved in the direct offer contract, we need to identify all atomic transactions that can take place.
+
+- Create an order
+- Reclaim an order
+- Execute an order
+
+These transactions represent the transaction families: Creating, Reclaiming, and Executing.
+
+A transaction family specification outlines the details necessary for transaction validation.
+
+The transaction family itself is an authorised script that can be implemented with any validator types. However, it is recommended to use the staking validator, as it only requires a zero withdrawal to activate this validator.
+
+For the all possible details of how to specify a transaction validation we encourage to use the templates in the ./template/ directory.
+
+Visit the direct offer specification examples for guidance on how to specify validation for the transaction families: [Creating](/ytxp-plutarch/examples/direct-offer/doc/transaction-families/creating.md), [Executing](/ytxp-plutarch/examples/direct-offer/doc/transaction-families/executing.md ), and [Reclaiming](/ytxp-plutarch/examples/direct-offer/doc/transaction-families/reclaiming.md).
+
+### Transaction flows
+
+We do not have any transaction flow for the offer contract. A transaction flow typically outlines one or more transaction families, which is often relevant in the context of a sub-state machine.
+
+## Closing Remarks
+
+You can find the complete specifications for the direct offer [here](/ytxp-plutarch/examples/direct-offer/doc/README.md).