Extended to Off-chain chapter transition

plutus-book/doc/09-extended.adoc

@@ -19,7 +19,10 @@ The extension has two components:
 transactions and the corresponding processing scheme performed by the nodes
 . an
 extension to the wallet backend to facilitate off-chain code that coordinates
-the execution of on-chain computations.
+the execution of on-chain computations
+- Note that an extended UTxO wallet must have access to ledger data in
+order to be able to watch (or to look up) outputs at specified addresses
+at any time
 
 In this chapter, we focus on the first component.
 In the extended UTxO model, additional on-chain computations must be done to
@@ -51,10 +54,16 @@ script capability to the second step.
 
 == Scripts
 
-Scripts (specifically, Plutus scripts) are Plutus Core expressions carried by
-a transaction. Scripts are a way to add smart contract functionality
-to the extended UTxO model. Many of the subsequent chapters of this book discuss building and
-executing scripts that define specific smart contracts. In this section, however,
+Recall from the <<10-PlutusTx#10-PlutusTx>> chapter that
+scripts (specifically, Plutus scripts) are Plutus Core expressions carried by
+a transaction (or stored on the ledger). They are defined inside a specially-delimited
+sections of a Haskell program, called Plutus Tx, which are then compiled into
+Plutus Core.
+
+Scripts are a way to add smart contract functionality
+to the extended UTxO model.
+Many of the subsequent chapters of this book discuss building scripts
+that define specific smart contracts. In this section, however,
 we discuss in general how scripts are used in the extended UTxO model.
 For a draft of the formal specification of the extended UTxO model with
 scripts, see <<scripts>>.
@@ -316,18 +325,3 @@ rolled back transaction. We do not give the details of this functionality here.
 
 There are other features of the extended UTxO system that are less relevant to
 a Plutus user, which we will also not explain in detail in this chapter.
-
-.Adding Ledger Functionality Using Scripts
-
-In the upcoming examples in this book we walk the reader through the process
-of building, testing and using Plutus contracts. For examples of work on using
-scripts to add specific functionality to the UTxO ledger, we would like to
-point the reader to the following documents,
-
-* Multi-currency on the UTXO Ledger, see <<multicur>>
-- A implementation of a script-based model for different types of
-currency as well as non-fungible tokens on the mockchain
-* A Formal Specification of a Multi-Signature Scheme Using Scripts, see <<multisig>>
-- A formal specification of enforcing a custom witnessing policy for spending
-outputs
-

plutus-book/doc/10-PlutusTx.adoc

@@ -5,12 +5,17 @@
 
 Plutus Tx is the name that we give to specially-delimited sections of a Haskell
 program which will be compiled into Plutus Core (that usually go in a transaction,
-hence the "Tx").
-
-This means that Plutus Tx is just Haskell. Strictly speaking, only a subset of Haskell is
+hence the "Tx"). So, the resulting Plutus Core expressions can be part of transaction
+data, or data stored on the ledger. These pieces of code require special processing
+on the blockchain and are referred to as Plutus scripts. We will discuss the
+mechanism by which they are used to control the transfer of funds in the
+next chapter, <<09-extended#09-extended>>.
+
+These special Plutus Tx sections in a Haskell program are themselves just Haskell.
+Strictly speaking, only a subset of Haskell is
 supported, but the majority of simple Haskell should work, and the compiler will tell you if
 you use something that is unsupported.
-This chapter is an explanation of the the PlutusTx language. For an in-depth
+This chapter is an explanation of the the Plutus Tx language. For an in-depth
 discussion of the nature of Plutus Core, which Plutus Tx compiles to, see <<plutuscore>>.
 
 The key technique that the Plutus Platform uses is called staged metaprogramming.
@@ -88,7 +93,7 @@ the integer `1`.
 
 NOTE: The Plutus Core syntax will look unfamiliar. This is fine, since it is
 the "assembly language" and you won’t need to inspect the output of
-the compiler. However, for the purposes of this tutorial it’s
+the compiler. However, for the purposes of this chapter it’s
 instructive to look at it to get a vague idea of what’s going on.
 
 [source,haskell]

plutus-book/doc/game/game.adoc

@@ -84,5 +84,4 @@ image:guessing-game-txs.png[]
 This concludes our first example of a Plutus smart contract combining on-chain
 with off-chain code. We have seen how to lift types and values to Plutus Core,
 how to write a validator script and how to interact with a script address in the
-iwallet.
-
+wallet.

plutus-book/doc/off-chain/off-chain.adoc

@@ -2,9 +2,59 @@
 = Writing off-chain code
 
 Working with Plutus requires writing on-chain code and off-chain code,
-with both parts working well together.
+with both parts working well together. Before diving into writing our code,
+we give a brief summary of
+what a complete Plutus contract consists of, and the role of on- and
+off-chain code in it.
 
-Let us start by looking at the off-chain part of this interplay,
+.The Plutus Contract
+[NOTE]
+====
+* A Plutus contract is a Haskell program which
+- runs in a user's wallet
+- also submits code (scripts) to the blockchain to be run by the nodes
+
+* Inside a Plutus smart contract definition, we have _endpoints_
+- endpoints are functions executed by the wallet to engage in the smart contract
+being defined (often parametrized by user-input data)
+- endpoints are _off-chain_ functions
+- endpoints are used to build transactions and submit them to be processed
+- endpoints call functions which generate Plutus
+Tx code (specifically the validator, redeemer, and data scripts)
+to be included in a transaction and executed by _on-chain_ by nodes
+
+* Besides endpoints, a Plutus contract definition may contain
+- all the necessary imports
+- a datatype definition, representing immutable information about a specific
+instance of a contract,
+such as the owner of the contract and any deadlines involved in the contract,
+e.g. `Campaign` or `Game`
+- functions which build a validator, redeemer and data scripts for the contract,
+usually parametrized by a term of that type (`Campaign`, `Game`, etc.)
+- event trigger and handler definitions for the execution of the endpoints
+- any auxiliary functions needed for the computations
+
+* Off-chain (endpoint) code can be executed by any wallet implementing a specific API
+via a wallet monad (as discussed below)
+- this allows the wallet the perform wallet-specific computations, including
+building transactions, catching and throwing errors, logging messages, etc.
+
+* On-chain (Plutus Tx) code is generated at compile time
+- defined inside a Plutus contract and included in transactions generated
+by the endpoints
+- executed by nodes to authorize spending script outputs by a transaction
+
+* A Plutus contract should, at the very least, contain endpoints which, by using the
+validator, redeemer and data scripts, generate transactions
+which allow the user to
+- _pay into_ a contract (this involves using the validator and redeemer scripts to create
+an unspent output belonging to the contract)
+- _spend_ from a contract (this will require a node to perform on-chain computation on the
+specific validator, redeemer and data scripts to unlock the output being spent)
+
+====
+
+Let us start by looking at the off-chain part of a Plutus contract,
 code that will be executed by the wallet.
 
 Such code is represented by a monadic computation in any monad
@@ -252,4 +302,3 @@ a certain action,
 and how to create, inspect, and use slot ranges.
 
 In the next chapter, we will dive into _on-chain_ code and create our first smart contract.
-

plutus-book/doc/off-chain/payToWallet1.adoc

@@ -29,7 +29,7 @@ myPayToWallet wallet ada = do
 
 $(mkFunctions ['myPayToWallet])
 ----
-<1>The `myPayToWallet` function takes two arguments,
+<1> The `myPayToWallet` function takes two arguments,
 the wallet for sending funds, and the amount to send.
 <2> We can look up the public key of a wallet with
 `walletPubKey`.