Add a page about different notions of version

doc/docusaurus/docs/essential-concepts/ledger.md

@@ -1,17 +1,17 @@
 ---
-sidebar_position: 10
+sidebar_position: 20
 ---
 
 # Ledgers
 
 The Plutus Platform is designed to work with distributed ledgers, which we'll just call "ledgers" from now on.
-Ledgers are typically *implemented* with a blockchain, such as Cardano. 
+Ledgers are typically *implemented* with a blockchain, such as Cardano.
 However, much of the time when we are talking about ledgers, we don't care about the underlying
 implementation, and so we will just talk about the ledger itself.
 
-> :pushpin: **NOTE** 
-> 
-> This is not always true: applications do need to care about details of how the underlying blockchain works, because that affects behaviour such as settlement time and rollback policies. 
+> :pushpin: **NOTE**
+>
+> This is not always true: applications do need to care about details of how the underlying blockchain works, because that affects behaviour such as settlement time and rollback policies.
 > As much as possible, the Plutus Application Framework tries to shield developers from this complexity, but it is not always possible.
 
 In its simplest form, a ledger is a system that tracks who owns what.
@@ -23,8 +23,8 @@ For example:
 | Alice | 43 USD  |
 | Bob   | 12 USD  |
 
-Ledgers are typically transformed by performing a *transaction* that transfers some assets from one party to another. 
-In order to be *valid*, a transaction will have to pass some checks, such as demonstrating that the transfer is authorized by the owner of the funds. 
+Ledgers are typically transformed by performing a *transaction* that transfers some assets from one party to another.
+In order to be *valid*, a transaction will have to pass some checks, such as demonstrating that the transfer is authorized by the owner of the funds.
 After applying a transaction (say, Alice sends Bob 5 USD), we have a new state of the ledger.
 
 | Owner | Balance |
@@ -35,39 +35,39 @@ After applying a transaction (say, Alice sends Bob 5 USD), we have a new state o
 ## Account-based and UTXO-based ledgers
 
 There are two dominant paradigms for how to *represent* such a system.
-The first, account-based ledgers, model the system exactly as in our example above. 
-They keep a list of accounts, and for each account, a balance. 
+The first, account-based ledgers, model the system exactly as in our example above.
+They keep a list of accounts, and for each account, a balance.
 A transaction simply decreases the balance of the sender, and increases the balance of the recipient.
 
-Account-based ledgers (such as Ethereum) are very simple to implement, but they have difficulties due to the fact that the state of an account is *global*: all transactions that do anything with an account must touch this one number. 
+Account-based ledgers (such as Ethereum) are very simple to implement, but they have difficulties due to the fact that the state of an account is *global*: all transactions that do anything with an account must touch this one number.
 This can lead to issues with throughput, as well as ordering issues (if Alice sends 5 USD to Bob, and Bob sends 5 USD to Carol, this may succeed or fail depending on the order in which the transactions are processed).
 
-The second paradigm is UTXO-based ledgers. 
+The second paradigm is UTXO-based ledgers.
 UTXO-based ledgers (such as Bitcoin) represent the state of the ledger as a set of "unspent
-transaction outputs" (UTXOs). 
-A UTXO is like an envelope with some money in it: it is "addressed" to a particular party, and it contains some funds. 
+transaction outputs" (UTXOs).
+A UTXO is like an envelope with some money in it: it is "addressed" to a particular party, and it contains some funds.
 A transaction *spends* some number of UTXOs, and creates some more.
 
 So a transaction that sends 5 USD from Alice to Bob would do so by spending some number of already-existing UTXOs belonging to Alice, and creating a new UTXO with 5 USD belonging to Bob.
 
-UTXO-based ledgers are more complicated, but avoid some of the issues of account-based ledgers, since any transaction deals only with the inputs that it spends. 
-Cardano is a UTXO-based ledger, and we heavily rely on this. 
+UTXO-based ledgers are more complicated, but avoid some of the issues of account-based ledgers, since any transaction deals only with the inputs that it spends.
+Cardano is a UTXO-based ledger, and we heavily rely on this.
 For example, [Hydra](../reference/glossary.md#hydra), Cardano's scalability solution, uses the fact that independent parts of the transaction graph can be processed in parallel to improve throughput.
 
 ## Scripts and the Extended UTXO Model
 
-UTXO-based ledgers typically start out with a very simple model of "ownership" of UTXOs. 
-An output will have a public key (strictly, the hash of a public key) attached to it, and in order to spend this output, the spending transaction must be signed by the corresponding private key. 
+UTXO-based ledgers typically start out with a very simple model of "ownership" of UTXOs.
+An output will have a public key (strictly, the hash of a public key) attached to it, and in order to spend this output, the spending transaction must be signed by the corresponding private key.
 We call this a "pay-to-pubkey" output.
 
-Cardano uses an extended model called the [Extended UTXO Model](../reference/glossary.md#extended-utxo-model) (EUTXO). 
-In the EUTXO model, an output can be locked by (the hash of) a *script*. 
-We call this a "pay-to-script" output. 
+Cardano uses an extended model called the [Extended UTXO Model](../reference/glossary.md#extended-utxo-model) (EUTXO).
+In the EUTXO model, an output can be locked by (the hash of) a *script*.
+We call this a "pay-to-script" output.
 A script is a *program* that decides whether or not the transaction which spends the output is
-authorized to do so. 
+authorized to do so.
 Such a script is called a validator script, because it validates whether the spending is allowed.
 
-A simple validator script would be one that checked whether the spending transaction was signed by a particular key—this would exactly replicate the behaviour of simple pay-to-pubkey outputs. 
+A simple validator script would be one that checked whether the spending transaction was signed by a particular key—this would exactly replicate the behaviour of simple pay-to-pubkey outputs.
 However, with a bit of careful extension, we can use scripts to let us express a large amount of useful logic on the chain.
 
 ## Three arguments passed to validator scripts
@@ -86,22 +86,22 @@ As an example, let's see how we could implement an atomic swap.
 
 ### Logic of the validator script
 
-The logic of the validator script, then, is as follows: 
-- Does the transaction make a payment from the second party to the first party, containing the value that they are supposed to send? 
+The logic of the validator script, then, is as follows:
+- Does the transaction make a payment from the second party to the first party, containing the value that they are supposed to send?
 - If so, then they may spend this output and send it where they want (or we could insist that they send it to their key, but we might as well let them do what they like with it).
 
 ## Different kinds of scripts
 
 The Cardano ledger currently has a few different kinds of validator scripts:
 
 - The "simple" script language (introduced in the Allegra hard fork), which allows basic checks such as time locks
-- Various Plutus language versions (see [Plutus language versions](language-versions.md))
+- Various ledger language versions (see [Different Notions of Version](versions.md))
 
 ## Further reading
 
 See [The EUTXO Handbook, A deep dive into Cardano's accounting model](https://www.essentialcardano.io/article/the-eutxo-handbook).
 
-For more help on how to actually implement interesting logic using the EUTXO model and scripts, see: 
+For more help on how to actually implement interesting logic using the EUTXO model and scripts, see:
 
 - [Using Plutus Tx](../category/using-plutus-tx)
 - [Working with scripts](../category/working-with-scripts)

doc/docusaurus/docs/essential-concepts/plutus-platform.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 10
 ---
 
 # Plutus platform
@@ -8,7 +8,7 @@ The Plutus platform is a platform for writing *applications* that interact with
 
 ## Example application
 
-What sort of "applications" are we talking about here? 
+What sort of "applications" are we talking about here?
 As an example, let's think about an application that provides the function of helping a pair of users, Alice and Bob, who want to engage in an atomic swap of some assets stored on Cardano.
 
 ### Alice initiates the swap
@@ -22,11 +22,11 @@ graph TD;
     classDef default fill:#33B6FF,stroke:#333,stroke-width:2px;
 ```
 
-- **Alice:** tells the Application, "I want to do an escrowed swap with Bob, 50 Ada for my Special Token." 
+- **Alice:** tells the Application, "I want to do an escrowed swap with Bob, 50 Ada for my Special Token."
 - **Application:** tells the Ledger, "I want to lock up Alice's Special Token so that it can only be unlocked if Bob completes the swap."
-- **Ledger:** responds to the Application, "Ok, that change has settled." 
+- **Ledger:** responds to the Application, "Ok, that change has settled."
 
-### Application interacts with Bob, Cardano and the ledger to execute the swap 
+### Application interacts with Bob, Cardano and the ledger to execute the swap
 
 ```mermaid
 graph TD;
@@ -45,13 +45,13 @@ graph TD;
 ```
 
 
-- **Application:** tells Bob, "Hey, Alice wants to do a swap with you." 
-- **Bob:** tells the Application, "I want to take up Alice's swap." 
-- **Application:** communicates to Cardano, "I want to spend that locked output with Alice's Special Token while sending 50 of Bob's Ada to Alice." 
-- **Ledger:** checks with itself: "Does this transaction satisfy the conditions that were asked for? Yes it does!" 
+- **Application:** tells Bob, "Hey, Alice wants to do a swap with you."
+- **Bob:** tells the Application, "I want to take up Alice's swap."
+- **Application:** communicates to Cardano, "I want to spend that locked output with Alice's Special Token while sending 50 of Bob's Ada to Alice."
+- **Ledger:** checks with itself: "Does this transaction satisfy the conditions that were asked for? Yes it does!"
 - **Ledger:** tells the Application, "Ok, that change has settled."
 
-### Application communicates that the swap completed 
+### Application communicates that the swap completed
 
 ```mermaid
 graph TD;
@@ -61,31 +61,30 @@ graph TD;
     classDef default fill:#33B6FF,stroke:#333,stroke-width:2px;
 ```
 
-- **Application:** tells Alice, "The swap is completed!" 
+- **Application:** tells Alice, "The swap is completed!"
 - **Application:** tells Bob, "The swap is completed!"
 
-Alice and Bob don't interact directly, nor do they directly interact with the ledger. 
-Very few "smart" blockchain systems encourage their users to interact directly with the chain themselves, since this is usually complex and error-prone. 
+Alice and Bob don't interact directly, nor do they directly interact with the ledger.
+Very few "smart" blockchain systems encourage their users to interact directly with the chain themselves, since this is usually complex and error-prone.
 Rather, the users interact with some *application* that presents the world in a form that they can understand and interact with.
 
-Of course, such an application must want to do something with the ledger, otherwise you wouldn't need anything new. 
-Simple applications might do nothing more than submit basic transactions that transfer assets—imagine a simple "regular payments" application. 
+Of course, such an application must want to do something with the ledger, otherwise you wouldn't need anything new.
+Simple applications might do nothing more than submit basic transactions that transfer assets—imagine a simple "regular payments" application.
 However, our main focus is on applications that *do* use smart features in order to have a kernel of trusted code that is validated as part of the ledger.
 
-This enables applications that are not possible otherwise. 
-Alice and Bob need trusted logic in order to perform their swap: a "dumb" application could submit the transactions transferring the assets, but would have no recourse against Bob defecting. 
+This enables applications that are not possible otherwise.
+Alice and Bob need trusted logic in order to perform their swap: a "dumb" application could submit the transactions transferring the assets, but would have no recourse against Bob defecting.
 Using the smart features of the ledger ensures that Bob can't take Alice's token unless he *really does* send her the money, and it does this without involving a trusted third party.
 
 Creating and using the trusted kernel of code is the most technically difficult and security-sensitive part of the whole operation.
-Nonetheless, writing the rest of the application contains plenty of complexity. 
-Amongst other things, an application needs to deal with the software around the ledger (wallets, nodes, etc.); distributed systems issues such as settlement delays, inconsistent state between parties, and rollbacks; and simple user-experience issues like upgrades, state management and synchronization. 
+Nonetheless, writing the rest of the application contains plenty of complexity.
+Amongst other things, an application needs to deal with the software around the ledger (wallets, nodes, etc.); distributed systems issues such as settlement delays, inconsistent state between parties, and rollbacks; and simple user-experience issues like upgrades, state management and synchronization.
 Furthermore, while none of these are quite as security-critical as the trusted kernel, users certainly *can* be attacked through such applications, and even non-malicious bugs are likely to be quite upsetting when a user's money is at stake.
 
 Even simple applications must deal with this complexity, and for more advanced applications that deal with state across time, the difficulty is magnified.
 
 ## Additional resources
 
-- Michael Peyton-Jones and Jann Mueller introduce the Plutus platform in [this session](https://youtu.be/usMPt8KpBeI?si=4zkS3J7Bq8aFxWbU) from the Cardano 2020 event. 
+- Michael Peyton-Jones and Jann Mueller introduce the Plutus platform in [this session](https://youtu.be/usMPt8KpBeI?si=4zkS3J7Bq8aFxWbU) from the Cardano 2020 event.
 
 - The design of the platform is discussed in the [Plutus technical report](https://plutus.cardano.intersectmbo.org/resources/plutus-report.pdf).
-