diff --git a/doc/docusaurus/docs/delve-deeper/plutus-language-changes.md b/doc/docusaurus/docs/delve-deeper/plutus-language-changes.md deleted file mode 100644 index c5bcffdaf31..00000000000 --- a/doc/docusaurus/docs/delve-deeper/plutus-language-changes.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -sidebar_position: 25 ---- - -# Plutus language changes - -## Language versions - -See the documentation on `language versions ` for an explanation of what they are. - -### Plutus V1 - -`PlutusV1` was the initial version of Plutus, introduced in the Alonzo hard fork. - -### Plutus V2 - -`PlutusV2` was introduced in the Vasil hard fork. - -The main changes in `PlutusV2` were to the interface to scripts. -The `ScriptContext` was extended to include the following information: - -- The full "redeemers" structure, which contains all the redeemers used in the transaction -- Reference inputs in the transaction (proposed in [CIP-31](https://cips.cardano.org/cips/cip31/)) -- Inline datums in the transaction (proposed in [CIP-32](https://cips.cardano.org/cips/cip32/)) -- Reference scripts in the transaction (proposed in [CIP-33](https://cips.cardano.org/cips/cip33/)) - -## Examples - -- [Plutus V2 functionalities](https://github.com/IntersectMBO/cardano-node/blob/master/doc/reference/plutus/babbage-script-example.md) -- [How to use reference inputs](https://github.com/perturbing/vasil-tests/blob/main/reference-inputs-cip-31.md) -- [How to use inline datums](https://github.com/perturbing/vasil-tests/blob/main/inline-datums-cip-32.md) -- [How to reference scripts](https://github.com/perturbing/vasil-tests/blob/main/referencing-scripts-cip-33.md) -- [How to use collateral outputs](https://github.com/perturbing/vasil-tests/blob/main/collateral-output-cip-40.md) - -## Built-in functions and types - -Built-in functions and types can be introduced with just a hard fork. -In some cases they are also available only in particular language versions. -This section indicates in which hard fork particular built-ins were introduced, and any language version constraints. - -### Alonzo - -This is when the majority of the built-in types and functions were added to `PlutusV1`. -You can find an enumeration of them in **add cross-reference link** : [plutus-core-spec]. - -### Vasil - -All of the built-in types and functions from `PlutusV1` were added to `PlutusV2`. - -The following built-in function was added to `PlutusV2` only (i.e., it is not available in `PlutusV1`). - -- `serializeData` (proposed in [CIP-42](https://cips.cardano.org/cips/cip42/)) - -### PlutusV3 - -Plutus and cryptography teams at IOG, in collaboration with [MLabs](https://mlabs.city/), continue to develop Plutus capabilities. -Starting with the release of [Cardano node v.8.8.0-pre](https://github.com/IntersectMBO/cardano-node/releases/tag/8.8.0-pre), `PlutusV3` is available on [SanchoNet](https://sancho.network/), introducing the Cardano community to governance features from [CIP-1694](https://cips.cardano.org/cip/CIP-1694#goal) in a controlled testnet environment. - -`PlutusV3` is the new ledger language that enhances Plutus Core's cryptographic capabilities, offering the following benefits for the smart contract developer community: - -- Providing an updated script context that will let users see [CIP-1694](https://cips.cardano.org/cip/CIP-1694#goal) governance-related entities and voting features -- Interoperability between blockchains -- Advanced Plutus primitives -- Well-known and optimal cryptographic algorithms -- Support for porting of smart contracts from Ethereum -- Creating sidechain bridges -- Improving performance by adding a sums of products (SOPs) feature to support the direct encoding of different data types. - -### Sums of products - -`PlutusV3` introduces sums of products - a way of encoding data types that leads to smaller and cheaper scripts compared with [Scott encoding](https://en.wikipedia.org/wiki/Mogensen%E2%80%93Scott_encoding), a common way of encoding data types in Plutus Core. - -The sums of products approach aims to boost script efficiency and improve code generation for Plutus Core compilers. -The changes involve new term constructors for packing fields into constructor values and efficient tag inspection for case branches, potentially running programs 30% faster. -For an in-depth discussion, see [CIP-85](https://cips.cardano.org/cip/CIP-0085). - -### New cryptographic primitives - -`PlutusV3` provides new built-in primitives that expand the language's capabilities. - -- **BLS12-381**: A curve pairing that includes 17 primitives that support cryptographic curves. This is a benefit to sidechain specification implementation and [Mithril](https://iohk.io/en/blog/posts/2023/07/20/mithril-nears-mainnet-release/) integration. -- **Blake2b-224**: A cryptographic hash function for on-chain computation of public-key hashes for the validation of transaction signatures. Supports community projects and contributes to Cardano's versatility. -- **Keccak-256**: A cryptographic hash function that produces a 256-bit (32-byte) hash value, commonly used for secure data verification. Supports Ethereum signature verification within scripts and cross-chain solutions. - -### Bitwise primitives - -PlutusV3 initially brings several new bitwise primitives (with more to come at later stages). -The introduction of [CIP-58](https://cips.cardano.org/cip/CIP-0058) bitwise primitives will enable the following features: - -- Very low-level bit manipulations within Plutus, supporting the ability to execute high-performance data manipulation operations. -- Supporting the implementation of secure and robust cryptographic algorithms within Plutus. -- Facilitating standard, high-performance implementations for conversions between integers and bytestrings. - -`PlutusV3` adds two bitwise primitives: `integerToByteString` and `byteStringToInteger`. -The remaining primitives will be added to `PlutusV3` gradually and will not require a new ledger language. - diff --git a/doc/docusaurus/docs/glossary.md b/doc/docusaurus/docs/glossary.md index 9074a1fa763..e266c59604a 100644 --- a/doc/docusaurus/docs/glossary.md +++ b/doc/docusaurus/docs/glossary.md @@ -45,6 +45,15 @@ See [_The Extended UTXO Model_](https://iohk.io/en/research/library/papers/the-e A guardrail script, sometimes referred to as a constitution script or a proposing script, is a Plutus V3 script used to validate two kinds of governance actions: parameter change and treasury withdrawal. See [Script Purposes](./working-with-scripts/script-purposes.md). +### Inline Datum + +Inline datums are a feature introduced in the Babbage era. +Before babbage, a UTXO could only contain a datum hash, not the datum itself. +To spend such a UTXO, the corresponding datum must be provided in the transaction. +Inline datums allow datums to be directly attached to UTXOs. + +For more details, see [CIP-32](https://cips.cardano.org/cip/CIP-32). + ### Hard Fork A hard fork is an update of the major protocol version, i.e., transitioning the protocol version from `x.y` to `x+1.0`. @@ -144,12 +153,48 @@ A piece of data included in a transaction that serves as an input to a Plutus sc If a smart contract is regarded as a state machine, the redeemer would be the input that ticks the state machine. +### Reference Input + +Reference inputs are a feature introduced in the Babbage era. +A reference input is a UTXO that a transaction can inspect without having to consume it. +Recall that a UTXO can only be consumed once. +Since a UTXO can only be consumed once, reference inputs help avoid the need to keep consuming and recreating similar UTXOs. + +For more details, see [CIP-31](https://cips.cardano.org/cip/CIP-31). + +### Reference Script + +Reference scripts are a feature introduced in the Babbage era. +Before Babbage, a UTXO could not contain scripts, so spending a UTXO with a script address required the script to be included in the transaction. +Reference scripts allow scripts to be attached to UTXOs, which can then be used as reference inputs. +This reduces transaction sizes, and avoids the need to include the same scripts in multiple transactions. + +For more details, see [CIP-33](https://cips.cardano.org/cip/CIP-33). + +### Scott Encoding + +Scott encoding is a method for encoding datatypes in lambda calculus. +The Plutus Tx compiler adopts Scott encoding for Plutus Tx datatypes when compiling to Plutus Core 1.0.0. +When compiling to Plutus Core 1.1.0, sums of products is used instead, which makes scripts smaller and cheaper compared to Scott encoding. +Currently, Plutus V1 and V2 are only compatible with Plutus Core 1.0.0, whereas Plutus V3 is also compatible with Plutus Core 1.1.0. +However, we plan to make all Plutus ledger language versions compatible with all Plutus Core versions in the future. + +For more details, see the [Wikipedia page](https://en.wikipedia.org/wiki/Mogensen%E2%80%93Scott_encoding) on Scott encoding. + ### Script Context An input to a Plutus script created by the ledger. It includes details of the transaction being validated. Additionally, since a transaction may do multiple things, each of which needs to be validated by a separate script, the script context also specifies what exactly the current script is responsible for validating. +### Sums of Products + +Sums of products is an alternative method to Scott encoding for encoding datatypes. +The Plutus Core language supports sums of products since version 1.1.0. +Currently, Plutus Core 1.1.0 is only compatible with Plutus V3, but we plan to make it compatible with Plutus V1 and V2 in the future. + +For more details, see [CIP-85](https://cips.cardano.org/cip/CIP-0085). + ### Typed Plutus Core The typed counterpart of Untyped Plutus Core, and can serve as a low-level IR for compilers targeting Untyped Plutus Core. diff --git a/doc/docusaurus/docs/working-with-scripts/ledger-language-version.md b/doc/docusaurus/docs/working-with-scripts/ledger-language-version.md index 195cc7542e6..46aee599241 100644 --- a/doc/docusaurus/docs/working-with-scripts/ledger-language-version.md +++ b/doc/docusaurus/docs/working-with-scripts/ledger-language-version.md @@ -22,18 +22,20 @@ As a result, The script contexts for Plutus V1, V2 and V3 also have different fi We cannot modify the script context fields of an existing ledger language version once it is published, since it would break existing scripts. In general, a ledger language version cannot be used in a transaction, if the ledger language version was introduced in ledger era A, the transaction uses features in ledger era B, and A is earlier than B. -For instance, Plutus V1 (introduced in the Alonzo era) scripts cannot be used in a transaction which utilizes inline datum (a Babbage era feature); Plutus V2 (introduced in the Babbage era) scripts cannot be used in a transaction that registers a DRep (introduced in the Conway era)[^1]. +For instance, Plutus V1 (introduced in the Alonzo era) scripts cannot be used in a transaction which utilizes inline datums (a Babbage era feature); Plutus V2 (introduced in the Babbage era) scripts cannot be used in a transaction that registers a DRep (introduced in the Conway era)[^1]. -## Plutus V1 and Plutus V2 +## Plutus V1 -Plutus V1 and Plutus V2 scripts have four [script purposes](https://plutus.cardano.intersectmbo.org/haddock/master/plutus-ledger-api/PlutusLedgerApi-V1-Contexts.html#t:ScriptPurpose): spending, minting, certifying, and rewarding[^2]. -The arguments a Plutus V1 or V2 script receives depend on the script purpose. -There is no requirement on the return value of a Plutus V1 and V2 script: script evaluation succeeds as long as the evaluation terminates without error, and the execution budget is not exceeded. +Plutus V1 is the initial ledger language version, enabled at the Alonzo hard fork, a hard fork that introduced the Alonzo era. + +Plutus V1 scripts have four [script purposes](https://plutus.cardano.intersectmbo.org/haddock/master/plutus-ledger-api/PlutusLedgerApi-V1-Contexts.html#t:ScriptPurpose): spending, minting, certifying, and rewarding[^2]. +The arguments a Plutus V1 script receives depend on the script purpose. +There is no requirement on the return value of a Plutus V1 script: script evaluation succeeds as long as the evaluation terminates without error, and the execution budget is not exceeded. ### Spending Scripts -A Plutus V1/V2 spending script receives three arguments corresponding to datum, redeemer and script context. +A Plutus V1 spending script receives three arguments corresponding to datum, redeemer and script context. All arguments are encoded as `BuiltinData`. Thus in Plutus Tx, a spending script has the following type: @@ -49,7 +51,6 @@ myV1SpendingScriptTyped :: MyDatum -> MyRedeemer -> PlutusLedgerApi.V1.ScriptCon ``` where `MyDatum` and `MyRedeemer` are your user-defined Haskell types specific to your contract. -If you are writing a Plutus V2 script, use `PlutusLedgerApi.V2.ScriptContext`. From `myV1SpendingScriptTyped`, you can obtain `BuiltinData -> BuiltinData -> BuiltinData -> any`, and subsequently compile it to UPLC, via @@ -72,11 +73,11 @@ Each call to `unsafeFromBuiltinData` decodes a `BuiltinData` into a value of a H The `check` function takes a `Bool` and returns a `BuiltinUnit`, throwing an error if the input is `False`. It is needed because returning `False` does not cause the validation to fail; to fail the validation, an error needs to be thrown. -In this example the script happens to return `BuiltinUnit`, but this is not a requirement for Plutus V1 or V2. +In this example the script happens to return `BuiltinUnit`, but this is not a requirement for Plutus V1. ### Minting, Certifying and Rewarding Scripts -Unlike spending scripts, Plutus V1 and V2 scripts for minting, certifying and rewarding purposes take one fewer argument: there is no datum argument. +Unlike spending scripts, Plutus V1 scripts for minting, certifying and rewarding purposes take one fewer argument: there is no datum argument. Thus in Plutus Tx, a minting, certifying or rewarding script should have the following type: ```haskell @@ -102,11 +103,29 @@ As said before, evaluating a Plutus V1 and V2 script succeeds as long as the eva This means, crucially, that an unsaturated script (a script expecting more arguments than it receives) succeeds trivially, since the evaluation terminates almost immediately and returns a lambda. Thus be careful: if, for example, you accidentally use a spending script (which expects three arguments) as a minting script (which will receive two arguments), it will always succeed, which is obviously not what you want. +## Plutus V2 + +Plutus V2 was enabled at the Vasil hard fork, which introduced the Babbage era. + +Plutus V2 shares several similarities with Plutus V1: +- It supports the same four script purposes. +- The number of arguments a Plutus V2 script receives is identical to Plutus V1: three for minting scripts, and two for other script purposes. +- Script evaluation succeeds as long as no errors occur and the budget is not exceeded. + +The differences between Plutus V1 and Plutus V2 include: +- Plutus V2 can be used in transactions that utilizes Babbage era features like [inline datums](https://cips.cardano.org/cip/CIP-0032) and [collateral output](https://cips.cardano.org/cip/CIP-0040), while Plutus V1 cannot (except for reference scripts, as noted earlier). +- Plutus V2's script context contains more fields than Plutus V1 due to new transaction features. + When writing a Plutus V2 script, you should use the `ScriptContext` data type from `PlutusLedgerApi.V2`. +- For now, Plutus V2 supports more builtin functions than Plutus V1, including `serialiseData`, `verifyEcdsaSecp256k1Signature` and `verifySchnorrSecp256k1Signature`. + However, as explained in [Different Notions of Version](../essential-concepts/versions.md), we plan to enable all builtin functions across all ledger language versions in the future. + ## Plutus V3 +Plutus V3 was enabled at the Chang hard fork, which introduced the Conway era. + Plutus V3 has two additional [script purposes](https://plutus.cardano.intersectmbo.org/haddock/master/plutus-ledger-api/PlutusLedgerApi-V3-Contexts.html#t:ScriptPurpose) for validating governance actions: voting and proposing. -Besides the usual differences between different Plutus ledger language versions, there are three additional key differences between Plutus V3 and V1/V2: +Additional key differences between Plutus V3 and V1/V2 include: 1. All Plutus V3 scripts, regardless of script purpose, take a single argument: the script context. The datum (for spending scripts) and the redeemer are part of the Plutus V3 script context. @@ -114,8 +133,10 @@ Besides the usual differences between different Plutus ledger language versions, 2. The datum is now optional for spending scripts. The script context may or may not contain a datum, depending on whether the UTXO being spent has a datum associated with it. 3. There is an additional condition for the evaluation of a Plutus V3 script to be considered successful: the return value must be a `BuiltinUnit`. +4. For now, Plutus V3 supports Plutus Core 1.1.0, a Plutus Core language version that introduced [sums-of-products](https://cips.cardano.org/cip/CIP-0085), as well as more builtin functions than Plutus V2. + However, we plan to enable all Plutus Core versions and all builtin functions across all ledger language versions in the future. -The first two points are attributed to [CIP-69](https://developers.cardano.org/docs/governance/cardano-improvement-proposals/cip-0069/), whereas the third point is attributed to [CIP-117](https://developers.cardano.org/docs/governance/cardano-improvement-proposals/cip-0117/). +The first two points above are attributed to [CIP-69](https://developers.cardano.org/docs/governance/cardano-improvement-proposals/cip-0069/), whereas the third point is attributed to [CIP-117](https://developers.cardano.org/docs/governance/cardano-improvement-proposals/cip-0117/). In other words, all Plutus V3 scripts should have the following type in Plutus Tx: @@ -127,6 +148,6 @@ Updating a Plutus V1/V2 script to turn it into a Plutus V3 script mostly involve --- -[^1]: There is one exception to this: Plutus V1 can be used in transactions with reference inputs, even though reference inputs were introduced in the Babbage era. +[^1]: There is one exception to this: Plutus V1 can be used in transactions with reference scripts, even though reference scripts were introduced in the Babbage era. [^2]: For more information on script purposes, refer to [Script Purposes](script-purposes.md).