diff --git a/doc/docusaurus/docs/essential-concepts/language-versions.md b/doc/docusaurus/docs/essential-concepts/language-versions.md deleted file mode 100644 index 90971b4d4a6..00000000000 --- a/doc/docusaurus/docs/essential-concepts/language-versions.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -sidebar_position: 20 ---- - -# Plutus language versions - -The Cardano ledger tags scripts with a *language*. -This determines what the ledger will do with the script. - -For example, the 'simple' script language introduced in the Allegra era allows for a few basic kinds of checks to be made, such as time locks. -To interpret simple scripts, the ledger must (among other things) extract the validation interval information from the transaction to check the conditions imposed by the script. - -Plutus scripts, introduced in the Alonzo era, have a more complex interface than simple scripts. -Plutus scripts are programs written in the Plutus Core programming language that receive three arguments: - -1. the datum -2. the redeemer, and -3. the context. - -The *context* contains all the information about the transaction which is currently being validated. (See [Scripts and the Extended UTXO model](ledger.md#scripts-and-the-extended-utxo-model) for more details). - -Languages must continue to behave the same forever; otherwise, we could change the behaviour of existing scripts, potentially making outputs un-spendable and breaking users' assumptions. -That means that many kinds of changes to the behaviour of the language instead require a "new" language. -This includes changes to the interface of the language. - -For example, if we want to put more information in the *context* (e.g., in order to convey information about new fields that have been added to transactions), then we need a new language, because old scripts would not be able to understand the new information. - -> :pushpin: **NOTE** -> -> For more details about what kinds of changes require a new language, see the Cardano Improvement Proposal, [CIP 35—Plutus Core Evolution](https://cips.cardano.org/cips/cip35/). - -Therefore, to change Plutus, we need to create a new language in the ledger. -Since, in most cases, this language will be very similar to the ones that came before, we refer to these as 'Plutus language versions.' -However, from the ledger's perspective, they are entirely unrelated and there is generally no requirement that they be similar or compatible in any way. - -There are two different uses of 'language' here that are important to keep distinct: - -1. Plutus Core is a *programming* language in which Plutus scripts are written -2. Plutus (the Plutus Core programming language and a particular interface) is a 'language' in the terminology of the ledger. - -In particular, a specific version of the Plutus Core programming language may be used in multiple versions of the Plutus ledger language, if, for example, the only difference is to the interface. -To date, all versions of Plutus use the same version of the Plutus Core. -That means that, in practice, the process for creating scripts of different Plutus language versions tends to be similar. -The main difference is that you will likely need a different `ScriptContext` type, and different -built-in functions may be available. - -*See also:* - -- [Plutus language changes](../reference/plutus-language-changes.md) for a description of what has changed between versions -- [Upgrading to Vasil and Plutus script addresses](../reference/upgrade-vasil-plutus-script-addresses.md). diff --git a/doc/docusaurus/docs/essential-concepts/ledger.md b/doc/docusaurus/docs/essential-concepts/ledger.md index 1f12d713a59..bb383174a47 100644 --- a/doc/docusaurus/docs/essential-concepts/ledger.md +++ b/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,8 +86,8 @@ 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 @@ -95,13 +95,13 @@ The logic of the validator script, then, is as follows: 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) diff --git a/doc/docusaurus/docs/essential-concepts/plutus-platform.mdx b/doc/docusaurus/docs/essential-concepts/plutus-platform.mdx index 03c9d999028..14021147012 100644 --- a/doc/docusaurus/docs/essential-concepts/plutus-platform.mdx +++ b/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). - diff --git a/doc/docusaurus/docs/essential-concepts/versions.md b/doc/docusaurus/docs/essential-concepts/versions.md new file mode 100644 index 00000000000..43fd4f3f561 --- /dev/null +++ b/doc/docusaurus/docs/essential-concepts/versions.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 5 +--- + +# Different Notions of Version + +There are several different notions of version that Cardano smart contract developers must distinguish. + +## Ledger Language Version + +This is what "Plutus V1", "Plutus V2", "Plutus V3" refer to. +It is called "ledger" language version because they are _not_ really different versions of a language in the sense of programming languages, but different languages from the Cardano ledger's point of view; the ledger handles Plutus V1 vs. V2 vs. V3 differently. +In essence, "Plutus V1", "Plutus V2" and "Plutus V3" are tags that the ledger attaches to validators in a transaction. + +From the ledger's perspective, they are in fact totally different languages: +there is no requirement that they be similar or compatible in any way. +However, the "V1", "V2" and "V3" naming scheme is practically useful because in reality they have a lot in common (e.g., the underlying language is Plutus Core and programs are executed by the Plutus Core evaluator, regardless of ledger language version); plus it makes it clear the order that they were introduced and the relationships among them. + +When simply writing a standalone program, say one that takes two integers and returns their sum, or one that implements a Sudoku solver, the notion of ledger language version is completely irrelevant. +There is no need (and nowhere) to specify whether you are writing a Plutus V1, or Plutus V2, or Plutus V3 program - again, the concept of ledger language version does not apply to programs themselves. +You simply write your code in Plutus Tx, compile it to UPLC, and run it with a UPLC evaluator. +This is what we mean by "they are not really different versions of a language in the sense of programming languages". + +It is only when you write a Plutus _validator script_, put it in a transaction and submit it to the Cardano ledger, that ledger language version becomes relevant. It is relevant in three ways: + +- Depending on the ledger language version, the ledger will pass different arguments to the validator. + For instance, the arguments passed to a Plutus V2 validator include a list of reference inputs of the transaction. This is not passed to a Plutus V1 validator since reference inputs were introduced later than Plutus V1 (specifically, Plutus V1 was introduced in the Alonzo era, while reference inputs were introduced in the Babbage era). + Similarly, only Plutus V3 can be used to validate governance actions, since governance actions are introduced in the Conway era and are not part of the pre-Conway era transactions, and thus aren't part of the arguments passed to Plutus V1 or V2 validators. +- At present, a newer ledger language version has access to more builtin functions than an older ledger language version. + Bear in mind that this will change as we plan to make all builtin functions available to all ledger language versions. +- At present, Plutus Core version (explained below) 1.1.0 can only be used with Plutus V3, while Plutus V1 and V2 validators must use Plutus Core 1.0.0. + This will also change, as we plan to make all Plutus Core versions compatible with all ledger language versions. + +When do we introduce a new ledger language version? +A new ledger language version must be introduced when a new ledger era is rolled out, because in a new ledger era, transactions will be different and contain new and/or modified fields, such as governance actions introduced in the Conway era. +As a result, new information will need to be passed as arguments to Plutus validators. +This necessitates a new ledger language version, because the arguments passed to existing ledger language versions must stay exactly the same, so that existing validators continue to work. + +Previously it was also the case that introducing new builtin functions or new Plutus Core versions necessitate a new ledger language version, but this is no longer the case. +Introducing a new ledger language version is very expensive as it must be maintained forever. +Going forward we expect the launch of new ledger eras to be the only reason for introducing new ledger language versions. + +## Plutus Core Version + +Plutus Core version is the usual sense of version pertaining to programming languages - in this instance the Plutus Core language. +So far there have been two Plutus Core versions: 1.0.0 and 1.1.0. +1.1.0 adds sums-of-products to the language by introducing two new AST node types: `Case` and `Constr`. +See [CIP-85](https://cips.cardano.org/cip/CIP-0085) for more details. + +Note that adding new builtin functions does not require a new Plutus Core version. +Once a new builtin function is added, one can simply start using the new builtin function with an existing Plutus Core version. + +## Builtin Semantics Variant + +Depending on the protocol version or the ledger language version, or both, we may want to have different behavior of a particular builtin function. +For example, we might want to fix a bug but need to retain the old buggy behavior for old evaluations of already-submitted scripts, so we have to have a way of knowing which regime we are in. + +One example is the builtin function `consByteString`. +If the first argument is outside of the range of `Word8`, the original behavior is to wrap it around. +The new behavior starting at Plutus V3 is to throw an exception. + +When evaluating a standalone program using the `uplc` executable, flag `-S` or `--builtin-semantics-variant` can be used to inform the evaluator which semantics variant to use. + +## Plutus Haskell Package Version + +Several Plutus components are regularly released as libraries, such as `plutus-core`, `plutus-ledger-api` and `plutus-tx-plugin`. +These packages are published on the [Cardano Haskell Package repository](https://github.com/IntersectMBO/cardano-haskell-packages) (CHaP), rather than Hackage, Haskell's default package archive. +Each release has a version following a standard release versioning scheme, and this is completely orthogonal and irrelevant to all other aformentioned notions of version. diff --git a/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md b/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md index c000ef385e5..1ed60cc0c6c 100644 --- a/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md +++ b/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md @@ -13,7 +13,7 @@ These options can be passed to the compiler via the `OPTIONS_GHC` pragma, for in ``` haskell {-# OPTIONS_GHC -fplugin-opt PlutusTx.Plugin:dump-uplc #-} -{-# OPTIONS_GHC -fplugin-opt PlutusTx.Plugin:max-simplifier-iterations=3 #-} +{-# OPTIONS_GHC -fplugin-opt PlutusTx.Plugin:max-simplifier-iterations-uplc=3 #-} ``` For each boolean option, you can add a `no-` prefix to switch it off, such as `no-typecheck`, `no-simplifier-beta`.