Merge branch 'master' of github.com:IntersectMBO/plutus into uplc2025

Author: zliu41

.github/workflows/manual-benchmark.yml

@@ -29,8 +29,10 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4.3.0
         with:
-          # We need at least one commit before master to compare against
-          fetch-depth: 5
+          # It's possible that new commits get merged into master since the PR 
+          # was opened. We need a safe buffer to make sure that our use of merge-head 
+          # leter always finds the true parent of the first PR commit.
+          fetch-depth: 100
 
       - name: React With Rocket 
         uses: actions/github-script@v7.1.0

.gitignore

@@ -120,3 +120,4 @@ TestCert.*
 **/_site/**/**
 **/.jekyll-metadata
 **/.jekyll-cache
+worktrees

cardano-constitution/cardano-constitution.cabal

@@ -1,6 +1,6 @@
 cabal-version:      3.0
 name:               cardano-constitution
-version:            1.53.0.0
+version:            1.54.0.0
 license:            Apache-2.0
 license-files:
   LICENSE
@@ -86,10 +86,10 @@ library
     , base               >=4.9   && <5
     , containers
     , filepath
-    , plutus-core        ^>=1.53
-    , plutus-ledger-api  ^>=1.53
-    , plutus-tx          ^>=1.53
-    , plutus-tx-plugin   ^>=1.53
+    , plutus-core        ^>=1.54
+    , plutus-ledger-api  ^>=1.54
+    , plutus-tx          ^>=1.54
+    , plutus-tx-plugin   ^>=1.54
     , regex-tdfa
     , safe
     , template-haskell
@@ -132,10 +132,10 @@ test-suite cardano-constitution-test
     , containers
     , directory
     , filepath
-    , plutus-core                      ^>=1.53
+    , plutus-core                      ^>=1.54
     , plutus-core:plutus-core-testlib
-    , plutus-ledger-api                ^>=1.53
-    , plutus-tx                        ^>=1.53
+    , plutus-ledger-api                ^>=1.54
+    , plutus-tx                        ^>=1.54
     , QuickCheck
     , serialise
     , tasty
@@ -152,4 +152,4 @@ executable create-json-envelope
   build-depends:
     , base
     , cardano-constitution
-    , plutus-ledger-api     ^>=1.53
+    , plutus-ledger-api     ^>=1.54

doc/docusaurus/docs/upcoming-features/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Upcoming Features",
+  "position": 75,
+  "link": {
+    "type": "generated-index",
+    "description": "Features that are being developed and will be available in future versions of Plutus."
+  }
+}

doc/docusaurus/docs/upcoming-features/builtin-arrays.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 1
+---
+
+# Builtin Arrays
+
+:::danger Upcoming Feature
+**This is an upcoming feature that is not yet available for use.** The `BuiltinArray` type and related functions are currently under development and will be included in a future version of Plutus. This documentation is provided for preview purposes only.
+:::
+
+For multiple lookups by index, `BuiltinArray` provides significantly better performance than lists. The key advantage is in the lookup operations themselves.
+
+**Lookup Performance Comparison:**
+A single lookup at index 99 of a 100-element data structure shows that the CPU cost for lookup on a standard Plinth list (`[Integer]`, a sum-of-products type) is **206 times higher** than on a `BuiltinArray`.
+
+**Important Considerations:**
+Currently, `BuiltinArray` creation is implemented as conversion from lists, which involves traversing the entire list. This conversion cost should be factored into your performance calculations - the dramatic lookup performance improvement needs to be amortized over multiple lookups to justify the conversion overhead.
+
+As a rule of thumb, if you only need to perform a single lookup, the conversion cost may not be worthwhile. The benefits become apparent when performing several lookups on the same data structure.
+
+**Future Development:**
+In future language versions, arrays are planned to be added to the `Data`-encoded `ScriptContext` precisely to avoid these high conversion costs, allowing arrays to be provided directly without requiring conversion from lists.
+
+## Choosing Arrays vs Lists
+
+When designing your data structures, consider your access patterns:
+
+**Choose arrays when:**
+- You need multiple index-based lookups (e.g., `arr[42]`, `arr[17]`)
+- Your access pattern is primarily random access rather than sequential
+- The data structure size is relatively stable after creation
+- You're building lookup tables or similar structures
+
+**Choose lists when:**
+- You primarily need sequential access (head/tail operations, pattern matching)
+- You frequently prepend elements (`:` operator)
+- Your access pattern is mostly single-pass iteration
+- You're following functional programming patterns that work naturally with lists
+
+**Current limitations:**
+Note that you can't always choose arrays "from the start" because data often comes from external sources as lists (like elements in `ScriptContext`). This is why the conversion scenario is currently common, and why future versions plan to provide arrays directly in these contexts.
+
+Functions for working with `BuiltinArray` are available in the `PlutusTx.Builtins` module:
+
+```haskell
+import PlutusTx.Builtins 
+  ( BuiltinArray
+  , indexArray
+  , listToArray
+  , lengthOfArray
+  )
+```
+
+<details>
+  <summary>Lookup comparison: SOP List vs. BuiltinList vs. BuiltinArray</summary>
+  <LiteralInclude file="Example/Builtin/Array/Main.hs" language="haskell" />
+  
+  Result of the evaluation:
+  ![BuiltinArray Performance Comparison](/code/Example/Builtin/Array/Screenshot.png)
+</details>

doc/docusaurus/docs/using-plinth/evaluating-plinth.md

@@ -8,6 +8,10 @@ sidebar_position: 12
 
 However, it is also possible to evaluate `CompiledCode` without running a node. The Plutus evaluator, called the CEK Machine, can be used independently of the Cardano node for testing and troubleshooting. By evaluating Plinth programs locally, developers can not only obtain the immediate result of the code but also access the traces emitted during evaluation and the consumed execution budget.
 
+:::info Version Information
+This functionality was released in version 1.47.
+:::
+
 Let's consider the following example Plinth program:
 <LiteralInclude 
   file="Example/Evaluation/Main.hs" 
@@ -27,9 +31,12 @@ To compile it, use the `compile` function as described earlier in the [Compiling
   start="-- BEGIN CompiledCode" 
   end="-- END CompiledCode" />
 
-To evaluate `compiledCode`, add the `plutus-tx` and `plutus-ledger-api` dependencies to your cabal file:
+To evaluate `compiledCode`, add the following dependencies to your cabal file:
 ```cabal
-build-depends: plutus-tx, plutus-ledger-api
+build-depends: 
+  plutus-tx, 
+  plutus-tx:plutus-tx-testlib, 
+  plutus-ledger-api 
 ```
 
 This allows you to import the necessary functionality:

doc/docusaurus/docs/working-with-scripts/other-optimization-techniques.md

@@ -128,6 +128,11 @@ Traces can be expensive especially in terms of script sizes.
 It is advisable to use traces during development, but to remove them when deploying your scripts on mainnet.
 Traces can be removed via the `remove-trace` plugin flag.
 
+## Using `BuiltinArray` for index-based lookups
+
+For optimizing multiple index-based lookups, see the upcoming [Builtin Arrays](../upcoming-features/builtin-arrays.md) feature.
+
+
 ## Using `error` for faster failure
 
 Plutus scripts have access to one impure effect, `error`, which immediately terminates the script evaluation and will fail validation.

doc/docusaurus/docusaurus-examples.cabal

@@ -40,10 +40,10 @@ library docusaurus-code
 
   build-depends:
     , base               >=4.9   && <5
-    , plutus-core        ^>=1.53
-    , plutus-ledger-api  ^>=1.53
-    , plutus-tx          ^>=1.53
-    , plutus-tx-plugin   ^>=1.53
+    , plutus-core        ^>=1.54
+    , plutus-ledger-api  ^>=1.54
+    , plutus-tx          ^>=1.54
+    , plutus-tx-plugin   ^>=1.54
 
 executable example-cip57
   import:           lang, ghc-version-support, os-support
@@ -54,9 +54,9 @@ executable example-cip57
   build-depends:
     , base               ^>=4.18
     , containers
-    , plutus-ledger-api  ^>=1.53
-    , plutus-tx          ^>=1.53
-    , plutus-tx-plugin   ^>=1.53
+    , plutus-ledger-api  ^>=1.54
+    , plutus-tx          ^>=1.54
+    , plutus-tx-plugin   ^>=1.54
 
 executable example-evaluation
   import:           lang, ghc-version-support, os-support
@@ -66,9 +66,30 @@ executable example-evaluation
   other-modules:    Paths_docusaurus_examples
   build-depends:
     , base                         ^>=4.18
-    , plutus-ledger-api            ^>=1.53
-    , plutus-tx                    ^>=1.53
-    , plutus-tx-plugin             ^>=1.53
+    , plutus-ledger-api            ^>=1.54
+    , plutus-tx                    ^>=1.54
+    , plutus-tx-plugin             ^>=1.54
+    , plutus-tx:plutus-tx-testlib
+    , text
+
+  ghc-options:
+    -Wno-missing-signatures -fno-full-laziness
+    -fno-ignore-interface-pragmas -fno-omit-interface-pragmas
+    -fno-spec-constr -fno-specialise -fno-strictness
+    -fno-unbox-small-strict-fields -fno-unbox-strict-fields
+
+executable example-builtin-array
+  import:           lang, ghc-version-support, os-support
+  main-is:          Example/Builtin/Array/Main.hs
+  hs-source-dirs:   static/code
+  default-language: Haskell2010
+  other-modules:    Paths_docusaurus_examples
+  build-depends:
+    , base                         ^>=4.18
+    , colourista
+    , plutus-core                  ^>=1.54
+    , plutus-tx                    ^>=1.54
+    , plutus-tx-plugin             ^>=1.54
     , plutus-tx:plutus-tx-testlib
     , text
 
@@ -88,6 +109,6 @@ executable quickstart
     , base               >=4.9   && <5
     , base16-bytestring
     , bytestring
-    , plutus-ledger-api  ^>=1.53
-    , plutus-tx          ^>=1.53
-    , plutus-tx-plugin   ^>=1.53
+    , plutus-ledger-api  ^>=1.54
+    , plutus-tx          ^>=1.54
+    , plutus-tx-plugin   ^>=1.54